abg-dwarf-reader.cc

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
// -*- Mode: C++ -*-
//
// Copyright (C) 2013-2023 Red Hat, Inc.
//
// Author: Dodji Seketeli
 
/// @file
///
/// This file contains the definitions of the entry points to
/// de-serialize an instance of @ref abigail::corpus from a file in
/// elf format, containing dwarf information.
 
#include "abg-internal.h"
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>
#include <libgen.h>
#include <assert.h>
#include <limits.h>
#include <elfutils/libdwfl.h>
#include <dwarf.h>
#include <algorithm>
#include <cmath>
#include <cstring>
#include <deque>
#include <list>
#include <memory>
#include <ostream>
#include <sstream>
#include <stack>
#include <unordered_map>
#include <unordered_set>
#include <map>
 
#include "abg-ir-priv.h"
#include "abg-suppression-priv.h"
#include "abg-corpus-priv.h"
#include "abg-symtab-reader.h"
 
// <headers defining libabigail's API go under here>
ABG_BEGIN_EXPORT_DECLARATIONS
 
#include "abg-dwarf-reader.h"
#include "abg-elf-based-reader.h"
#include "abg-sptr-utils.h"
#include "abg-tools-utils.h"
#include "abg-elf-helpers.h"
 
ABG_END_EXPORT_DECLARATIONS
// </headers defining libabigail's API>
 
#ifndef UINT64_MAX
#define UINT64_MAX 0xffffffffffffffff
#endif
 
using std::string;
 
namespace abigail
{
 
using std::cerr;
 
/// The namespace for the DWARF reader.
namespace dwarf
{
 
using std::dynamic_pointer_cast;
using std::static_pointer_cast;
using std::unordered_map;
using std::unordered_set;
using std::stack;
using std::deque;
using std::list;
using std::map;
using abg_compat::optional;
 
using namespace elf_helpers; // TODO: avoid using namespace
 
/// Where a DIE comes from. For instance, a DIE can come from the main
/// debug info section, the alternate debug info section or from the
/// type unit section.
enum die_source
{
  NO_DEBUG_INFO_DIE_SOURCE,
  PRIMARY_DEBUG_INFO_DIE_SOURCE,
  ALT_DEBUG_INFO_DIE_SOURCE,
  TYPE_UNIT_DIE_SOURCE,
  NUMBER_OF_DIE_SOURCES,    // This one must always be the latest
                // enumerator
};
 
 
/// A convenience typedef for a vector of Dwarf_Off.
typedef vector<Dwarf_Off> dwarf_offsets_type;
 
/// Convenience typedef for a map which key is the offset of a dwarf
/// die and which value is the corresponding artefact.
typedef unordered_map<Dwarf_Off, type_or_decl_base_sptr> die_artefact_map_type;
 
/// Convenience typedef for a map which key is the offset of a dwarf
/// die, (given by dwarf_dieoffset()) and which value is the
/// corresponding class_decl.
typedef unordered_map<Dwarf_Off, class_decl_sptr> die_class_map_type;
 
/// Convenience typedef for a map which key is the offset of a dwarf
/// die, (given by dwarf_dieoffset()) and which value is the
/// corresponding class_or_union_sptr.
typedef unordered_map<Dwarf_Off, class_or_union_sptr> die_class_or_union_map_type;
 
/// Convenience typedef for a map which key the offset of a dwarf die
/// and which value is the corresponding function_decl.
typedef unordered_map<Dwarf_Off, function_decl_sptr> die_function_decl_map_type;
 
/// Convenience typedef for a map which key is the offset of a dwarf
/// die and which value is the corresponding function_type.
typedef unordered_map<Dwarf_Off, function_type_sptr> die_function_type_map_type;
 
/// Convenience typedef for a map which key is the offset of a
/// DW_TAG_compile_unit and the value is the corresponding @ref
/// translation_unit_sptr.
typedef unordered_map<Dwarf_Off, translation_unit_sptr> die_tu_map_type;
 
/// Convenience typedef for a map which key is the offset of a DIE and
/// the value is the corresponding qualified name of the DIE.
typedef unordered_map<Dwarf_Off, interned_string> die_istring_map_type;
 
/// Convenience typedef for a map which is an interned_string and
/// which value is a vector of offsets.
typedef unordered_map<interned_string,
              dwarf_offsets_type,
              hash_interned_string>
istring_dwarf_offsets_map_type;
 
/// A hasher for a pair of Dwarf_Off.  This is used as a hasher for
/// the type @ref dwarf_offset_pair_set_type.
struct dwarf_offset_pair_hash
{
  size_t
  operator()(const std::pair<Dwarf_Off, Dwarf_Off>& p) const
  {return abigail::hashing::combine_hashes(p.first, p.second);}
};// end struct dwarf_offset_pair_hash
 
typedef unordered_set<std::pair<Dwarf_Off,
                Dwarf_Off>,
              dwarf_offset_pair_hash> dwarf_offset_pair_set_type;
 
/// An abstraction of a DIE offset that also encapsulate the source of
/// the DIE.
struct offset_type
{
  die_source source_;
  Dwarf_Off offset_;
 
  offset_type()
    : source_(PRIMARY_DEBUG_INFO_DIE_SOURCE),
      offset_(0)
  {}
 
  offset_type(die_source source, Dwarf_Off offset)
    : source_(source),
      offset_(offset)
  {}
 
  offset_type(Dwarf_Off offset)
    : source_(PRIMARY_DEBUG_INFO_DIE_SOURCE),
      offset_(offset)
  {}
 
  bool operator==(const offset_type& o) const
  {return source_ == o.source_ && offset_ == o.offset_;}
 
  operator Dwarf_Off() const
  {return offset_;}
}; // end struct offset_type
 
/// A convenience typedef for a pair of offset_type.
typedef std::pair<offset_type, offset_type> offset_pair_type;
 
/// A hasher for an instance of offset_type.
struct offset_hash
{
  size_t
  operator()(const offset_type& p) const
  {return abigail::hashing::combine_hashes(p.source_, p.offset_);}
};// end struct offset_hash
 
/// A hasher for a pair of offset_type.  This is used as a hasher for
/// the type @ref offset_pair_set_type, for instance.
struct offset_pair_hash
{
  size_t
  operator()(const std::pair<offset_type, offset_type>& p) const
  {
    size_t h1 = abigail::hashing::combine_hashes(p.first.source_,
                           p.first.offset_);
    size_t h2 = abigail::hashing::combine_hashes(p.second.source_,
                           p.second.offset_);
    return abigail::hashing::combine_hashes(h1, h2);
  }
};// end struct offset_pair_hash
 
/// A convenience typedef for an unordered set of DIE offsets.
typedef unordered_set<offset_type, offset_hash> offset_set_type;
 
///A convenience typedef for an unordered set of pairs of offset_type.
typedef unordered_set<std::pair<offset_type,
                offset_type>,
              offset_pair_hash> offset_pair_set_type;
 
/// A convenience typedef for a vector of pairs of offset_type.
typedef vector<std::pair<offset_type, offset_type>> offset_pair_vector_type;
 
/// A convenience typedef for an unordered map that associates a pair
/// of offset_type to a vector of pairs offset_type.
typedef unordered_map<std::pair<offset_type, offset_type>,
              offset_pair_vector_type,
              offset_pair_hash> offset_pair_vect_map_type;
 
/// A convenience typedef for an unordered_map that associates a pair
/// of offset_type to a set of pairs of offset_type.
typedef unordered_map<std::pair<offset_type, offset_type>,
              offset_pair_set_type,
              offset_pair_hash> offset_pair_set_map_type;
 
/// A convenience typedef for a vector of pairs of offset_type.
typedef vector<std::pair<offset_type, offset_type>> offset_pair_vector_type;
 
class reader;
 
static translation_unit_sptr
build_translation_unit_and_add_to_ir(reader&    rdr,
                     Dwarf_Die* die,
                     char       address_size);
 
static void
maybe_propagate_canonical_type(const reader& rdr,
                   const Dwarf_Die* l,
                   const Dwarf_Die* r);
 
static void
propagate_canonical_type(const reader& rdr,
             const Dwarf_Die* l,
             const Dwarf_Die* r);
 
/// Convenience typedef for a shared pointer to an
/// addr_elf_symbol_sptr_map_type.
typedef shared_ptr<addr_elf_symbol_sptr_map_type> addr_elf_symbol_sptr_map_sptr;
 
/// Convenience typedef for a map that associates an @ref
/// interned_string to a @ref function_type_sptr.
typedef unordered_map<interned_string,
              function_type_sptr,
              hash_interned_string> istring_fn_type_map_type;
 
/// Convenience typedef for a stack containing the scopes up to the
/// current point in the abigail Internal Representation (aka IR) tree
/// that is being built.
typedef stack<scope_decl*> scope_stack_type;
 
/// Convenience typedef for a map which key is a dwarf offset.  The
/// value is also a dwarf offset.
typedef unordered_map<Dwarf_Off, Dwarf_Off> offset_offset_map_type;
 
/// Convenience typedef for a map which key is a string and which
/// value is a vector of smart pointer to a class_or_union_sptr.
typedef unordered_map<string, classes_or_unions_type> string_classes_or_unions_map;
 
/// Convenience typedef for a map which key is a string and which
/// value is a vector of smart pointer to a class.
typedef unordered_map<string, classes_type> string_classes_map;
 
/// Convenience typedef for a map which key is a string and which
/// value is a vector of smart pointer to a enum.
typedef unordered_map<string, enums_type> string_enums_map;
 
/// The abstraction of the place where a partial unit has been
/// imported.  This is what the DW_TAG_imported_unit DIE expresses.
///
/// This type thus contains:
/// - the offset to which the partial unit is imported
/// - the offset of the imported partial unit.
/// - the offset of the imported partial unit.
struct imported_unit_point
{
  Dwarf_Off offset_of_import;
  // The boolean below is true iff the imported unit comes from the
  // alternate debug info file.
  die_source    imported_unit_die_source;
  Dwarf_Off imported_unit_die_off;
  Dwarf_Off imported_unit_cu_off;
  Dwarf_Off imported_unit_child_off;
 
  /// Default constructor for @ref the type imported_unit_point.
  imported_unit_point()
    : offset_of_import(),
      imported_unit_die_source(PRIMARY_DEBUG_INFO_DIE_SOURCE),
      imported_unit_die_off(),
      imported_unit_cu_off(),
      imported_unit_child_off()
  {}
 
  /// Constructor of @ref the type imported_unit_point.
  ///
  /// @param import_off the offset of the point at which the unit has
  /// been imported.
  imported_unit_point(Dwarf_Off import_off)
    : offset_of_import(import_off),
      imported_unit_die_source(PRIMARY_DEBUG_INFO_DIE_SOURCE),
      imported_unit_die_off(),
      imported_unit_cu_off(),
      imported_unit_child_off()
  {}
 
  /// Constructor of @ref the type imported_unit_point.
  ///
  /// @param import_off the offset of the point at which the unit has
  /// been imported.
  ///
  /// @param from where the imported DIE comes from.
  ///
  /// @param imported_die the die of the unit that has been imported.
  imported_unit_point(Dwarf_Off import_off,
              const Dwarf_Die& imported_die,
              die_source from)
    : offset_of_import(import_off),
      imported_unit_die_source(from),
      imported_unit_die_off(dwarf_dieoffset
                (const_cast<Dwarf_Die*>(&imported_die))),
      imported_unit_cu_off(),
      imported_unit_child_off()
  {
    Dwarf_Die imported_unit_child;
 
    ABG_ASSERT(dwarf_child(const_cast<Dwarf_Die*>(&imported_die),
               &imported_unit_child) == 0);
 
    imported_unit_child_off =
      dwarf_dieoffset(const_cast<Dwarf_Die*>(&imported_unit_child));
 
    Dwarf_Die cu_die_memory;
    Dwarf_Die *cu_die;
 
    cu_die = dwarf_diecu(const_cast<Dwarf_Die*>(&imported_unit_child),
             &cu_die_memory, 0, 0);
    imported_unit_cu_off = dwarf_dieoffset(cu_die);
  }
}; // struct imported_unit_point
 
/// Convenience typedef for a vector of @ref imported_unit_point.
typedef vector<imported_unit_point> imported_unit_points_type;
 
/// Convenience typedef for a vector of @ref imported_unit_point.
typedef unordered_map<Dwarf_Off, imported_unit_points_type>
tu_die_imported_unit_points_map_type;
 
/// "Less than" operator for instances of @ref imported_unit_point
/// type.
///
/// @param the left hand side operand of the "Less than" operator.
///
/// @param the right hand side operand of the "Less than" operator.
///
/// @return true iff @p l is less than @p r.
static bool
operator<(const imported_unit_point& l, const imported_unit_point& r)
{return l.offset_of_import < r.offset_of_import;}
 
static bool
get_parent_die(const reader&    rdr,
           const Dwarf_Die* die,
           Dwarf_Die&       parent_die,
           size_t           where_offset);
 
static bool
get_scope_die(const reader& rdr,
          const Dwarf_Die*      die,
          size_t            where_offset,
          Dwarf_Die&        scope_die);
 
static bool
die_is_anonymous(const Dwarf_Die* die);
 
static bool
die_is_anonymous_data_member(const Dwarf_Die* die);
 
static bool
die_is_type(const Dwarf_Die* die);
 
static bool
die_is_decl(const Dwarf_Die* die);
 
static bool
die_is_declaration_only(Dwarf_Die* die);
 
static bool
die_is_variable_decl(const Dwarf_Die *die);
 
static bool
die_is_function_decl(const Dwarf_Die *die);
 
static bool
die_has_size_attribute(const Dwarf_Die *die);
 
static bool
die_has_no_child(const Dwarf_Die *die);
 
static bool
die_is_namespace(const Dwarf_Die* die);
 
static bool
die_is_unspecified(Dwarf_Die* die);
 
static bool
die_is_void_type(Dwarf_Die* die);
 
static bool
die_is_pointer_type(const Dwarf_Die* die);
 
static bool
pointer_or_qual_die_of_anonymous_class_type(const Dwarf_Die* die);
 
static bool
die_is_reference_type(const Dwarf_Die* die);
 
static bool
die_is_pointer_array_or_reference_type(const Dwarf_Die* die);
 
static bool
die_is_pointer_or_reference_type(const Dwarf_Die* die);
 
static bool
die_is_pointer_reference_or_typedef_type(const Dwarf_Die* die);
 
static bool
die_is_class_type(const Dwarf_Die* die);
 
static bool
die_is_qualified_type(const Dwarf_Die* die);
 
static bool
die_is_function_type(const Dwarf_Die *die);
 
static bool
die_has_object_pointer(const Dwarf_Die* die,
               Dwarf_Die& object_pointer);
 
static bool
die_has_children(const Dwarf_Die* die);
 
static bool
die_this_pointer_from_object_pointer(Dwarf_Die* die,
                     Dwarf_Die& this_pointer);
 
static bool
die_this_pointer_is_const(Dwarf_Die* die);
 
static bool
die_object_pointer_is_for_const_method(Dwarf_Die* die);
 
static bool
is_type_die_to_be_canonicalized(const Dwarf_Die *die);
 
static bool
die_is_at_class_scope(const reader& rdr,
              const Dwarf_Die* die,
              size_t where_offset,
              Dwarf_Die& class_scope_die);
static bool
eval_last_constant_dwarf_sub_expr(Dwarf_Op* expr,
                  size_t    expr_len,
                  int64_t&  value,
                  bool& is_tls_address);
 
static translation_unit::language
dwarf_language_to_tu_language(size_t l);
 
static bool
die_unsigned_constant_attribute(const Dwarf_Die*    die,
                unsigned        attr_name,
                uint64_t&       cst);
 
static bool
die_signed_constant_attribute(const Dwarf_Die*die,
                  unsigned  attr_name,
                  int64_t&  cst);
 
static bool
die_constant_attribute(const Dwarf_Die *die,
               unsigned attr_name,
               bool is_signed,
               array_type_def::subrange_type::bound_value &value);
 
static bool
die_member_offset(const reader& rdr,
          const Dwarf_Die* die,
          int64_t& offset);
 
static bool
form_is_DW_FORM_strx(unsigned form);
 
static bool
form_is_DW_FORM_line_strp(unsigned form);
 
static bool
die_address_attribute(Dwarf_Die* die, unsigned attr_name, Dwarf_Addr& result);
 
static string
die_name(const Dwarf_Die* die);
 
static location
die_location(const reader& rdr, const Dwarf_Die* die);
 
static bool
die_location_address(Dwarf_Die* die,
             Dwarf_Addr&    address,
             bool&      is_tls_address);
 
static bool
die_die_attribute(const Dwarf_Die* die,
          unsigned attr_name,
          Dwarf_Die& result,
          bool recursively = true);
 
static bool
subrange_die_indirect_bound_value(const Dwarf_Die *die,
                  unsigned attr_name,
                  array_type_def::subrange_type::bound_value& v,
                  bool& is_signed);
 
static bool
subrange_die_indirectly_references_subrange_die(const Dwarf_Die *die,
                        unsigned attr_name,
                        Dwarf_Die& referenced_subrange);
static string
get_internal_anonymous_die_prefix_name(const Dwarf_Die *die);
 
static string
build_internal_anonymous_die_name(const string &base_name,
                  size_t anonymous_type_index);
 
static string
get_internal_anonymous_die_name(Dwarf_Die *die,
                size_t anonymous_type_index);
 
static string
die_qualified_type_name(const reader& rdr,
            const Dwarf_Die* die,
            size_t where);
 
static string
die_qualified_decl_name(const reader& rdr,
            const Dwarf_Die* die,
            size_t where);
 
static string
die_qualified_name(const reader& rdr,
           const Dwarf_Die* die,
           size_t where);
 
static bool
die_qualified_type_name_empty(const reader& rdr,
                  const Dwarf_Die* die, size_t where,
                  string &qualified_name);
 
static void
die_return_and_parm_names_from_fn_type_die(const reader& rdr,
                       const Dwarf_Die* die,
                       size_t where_offset,
                       bool pretty_print,
                       string &return_type_name,
                       string &class_name,
                       vector<string>& parm_names,
                       bool& is_const,
                       bool& is_static);
 
static string
die_function_signature(const reader& rdr,
               const Dwarf_Die *die,
               size_t where_offset);
 
static bool
die_peel_qual_ptr(Dwarf_Die *die, Dwarf_Die& peeled_die);
 
static bool
die_peel_qualified(Dwarf_Die *die, Dwarf_Die& peeled_die);
 
static bool
die_function_type_is_method_type(const reader& rdr,
                 const Dwarf_Die *die,
                 size_t where_offset,
                 Dwarf_Die& object_pointer_die,
                 Dwarf_Die& class_die,
                 bool& is_static);
 
static string
die_pretty_print_type(reader& rdr,
              const Dwarf_Die* die,
              size_t where_offset);
 
static string
die_pretty_print_decl(reader& rdr,
              const Dwarf_Die* die,
              size_t where_offset);
 
static string
die_pretty_print(reader& rdr,
         const Dwarf_Die* die,
         size_t where_offset);
 
static void
maybe_canonicalize_type(const type_base_sptr&   t,
            reader&     rdr);
 
static uint64_t
get_default_array_lower_bound(translation_unit::language l);
 
static bool
find_lower_bound_in_imported_unit_points(const imported_unit_points_type&,
                     Dwarf_Off,
                     imported_unit_points_type::const_iterator&);
 
static array_type_def::subrange_sptr
build_subrange_type(reader& rdr,
            const Dwarf_Die*    die,
            size_t      where_offset,
            bool        associate_type_to_die = true);
 
static void
build_subranges_from_array_type_die(reader&         rdr,
                    const Dwarf_Die*            die,
                    array_type_def::subranges_type& subranges,
                    size_t              where_offset,
                    bool                associate_type_to_die = true);
 
static comparison_result
compare_dies(const reader& rdr,
         const Dwarf_Die *l, const Dwarf_Die *r,
         bool update_canonical_dies_on_the_fly);
 
static bool
compare_dies_during_canonicalization(reader& rdr,
                     const Dwarf_Die *l, const Dwarf_Die *r,
                     bool update_canonical_dies_on_the_fly);
 
static bool
get_member_child_die(const Dwarf_Die *die, Dwarf_Die *child);
 
/// Compare a symbol name against another name, possibly demangling
/// the symbol_name before performing the comparison.
///
/// @param symbol_name the symbol_name to take in account.
///
/// @param name the second name to take in account.
///
/// @param demangle if true, demangle @p symbol_name and compare the
/// result of the demangling with @p name.
///
/// @return true iff symbol_name equals name.
static bool
compare_symbol_name(const string& symbol_name,
            const string& name,
            bool demangle)
{
  if (demangle)
    {
      string m = demangle_cplus_mangled_name(symbol_name);
      return m == name;
    }
  return symbol_name == name;
}
 
/// Lookup a symbol using the SysV ELF hash table.
///
/// Note that this function hasn't been tested.  So it hasn't been
/// debugged yet.  IOW, it is not known to work.  Or rather, it's
/// almost like it's surely doesn't work ;-)
///
/// Use it at your own risks.  :-)
///
///@parm env the environment we are operating from.
///
/// @param elf_handle the elf_handle to use.
///
/// @param sym_name the symbol name to look for.
///
/// @param ht_index the index (in the section headers table) of the
/// hash table section to use.
///
/// @param sym_tab_index the index (in the section headers table) of
/// the symbol table to use.
///
/// @param demangle if true, demangle @p sym_name before comparing it
/// to names from the symbol table.
///
/// @param syms_found a vector of symbols found with the name @p
/// sym_name.  table.
static bool
lookup_symbol_from_sysv_hash_tab(const environment&     env,
                 Elf*               elf_handle,
                 const string&          sym_name,
                 size_t         ht_index,
                 size_t         sym_tab_index,
                 bool               demangle,
                 vector<elf_symbol_sptr>&   syms_found)
{
  Elf_Scn* sym_tab_section = elf_getscn(elf_handle, sym_tab_index);
  ABG_ASSERT(sym_tab_section);
 
  Elf_Data* sym_tab_data = elf_getdata(sym_tab_section, 0);
  ABG_ASSERT(sym_tab_data);
 
  GElf_Shdr sheader_mem;
  GElf_Shdr* sym_tab_section_header = gelf_getshdr(sym_tab_section,
                           &sheader_mem);
  Elf_Scn* hash_section = elf_getscn(elf_handle, ht_index);
  ABG_ASSERT(hash_section);
 
  // Poke at the different parts of the hash table and get them ready
  // to be used.
  unsigned long hash = elf_hash(sym_name.c_str());
  Elf_Data* ht_section_data = elf_getdata(hash_section, 0);
  Elf32_Word* ht_data = reinterpret_cast<Elf32_Word*>(ht_section_data->d_buf);
  size_t nb_buckets = ht_data[0];
  size_t nb_chains = ht_data[1];
 
  if (nb_buckets == 0)
    // An empty hash table.  Not sure if that is possible, but it
    // would mean an empty table of exported symbols.
    return false;
 
  //size_t nb_chains = ht_data[1];
  Elf32_Word* ht_buckets = &ht_data[2];
  Elf32_Word* ht_chains = &ht_buckets[nb_buckets];
 
  // Now do the real work.
  size_t bucket = hash % nb_buckets;
  size_t symbol_index = ht_buckets[bucket];
 
  GElf_Sym symbol;
  const char* sym_name_str;
  size_t sym_size;
  elf_symbol::type sym_type;
  elf_symbol::binding sym_binding;
  elf_symbol::visibility sym_visibility;
  bool found = false;
 
  do
    {
      ABG_ASSERT(gelf_getsym(sym_tab_data, symbol_index, &symbol));
      sym_name_str = elf_strptr(elf_handle,
                sym_tab_section_header->sh_link,
                symbol.st_name);
      if (sym_name_str
      && compare_symbol_name(sym_name_str, sym_name, demangle))
    {
      sym_type = stt_to_elf_symbol_type(GELF_ST_TYPE(symbol.st_info));
      sym_binding = stb_to_elf_symbol_binding(GELF_ST_BIND(symbol.st_info));
      sym_visibility =
        stv_to_elf_symbol_visibility(GELF_ST_VISIBILITY(symbol.st_other));
      sym_size = symbol.st_size;
      elf_symbol::version ver;
      if (get_version_for_symbol(elf_handle, symbol_index,
                     /*get_def_version=*/true, ver))
        ABG_ASSERT(!ver.str().empty());
      elf_symbol_sptr symbol_found =
        elf_symbol::create(env,
                   symbol_index,
                   sym_size,
                   sym_name_str,
                   sym_type,
                   sym_binding,
                   symbol.st_shndx != SHN_UNDEF,
                   symbol.st_shndx == SHN_COMMON,
                   ver, sym_visibility);
      syms_found.push_back(symbol_found);
      found = true;
    }
      symbol_index = ht_chains[symbol_index];
    } while (symbol_index != STN_UNDEF || symbol_index >= nb_chains);
 
  return found;
}
 
/// Get the size of the elf class, in bytes.
///
/// @param elf_handle the elf handle to use.
///
/// @return the size computed.
static char
get_elf_class_size_in_bytes(Elf* elf_handle)
{
  char result = 0;
  GElf_Ehdr hdr;
 
  ABG_ASSERT(gelf_getehdr(elf_handle, &hdr));
  int c = hdr.e_ident[EI_CLASS];
 
  switch (c)
    {
    case ELFCLASS32:
      result = 4;
      break;
    case ELFCLASS64:
      result = 8;
      break;
    default:
      ABG_ASSERT_NOT_REACHED;
    }
 
  return result;
}
 
/// Get a given word of a bloom filter, referred to by the index of
/// the word.
///
/// The bloom word size depends on the current elf class (32 bits for
/// an ELFCLASS32 or 64 bits for an ELFCLASS64 one) and this function
/// abstracts that nicely.
///
/// @param elf_handle the elf handle to use.
///
/// @param bloom_filter the bloom filter to consider.
///
/// @param index the index of the bloom filter to return.
///
/// @return a 64 bits work containing the bloom word found at index @p
/// index.  Note that if we are looking at an ELFCLASS32 binary, the 4
/// most significant bytes of the result are going to be zero.
static Elf64_Xword
bloom_word_at(Elf*      elf_handle,
          Elf32_Word*   bloom_filter,
          size_t        index)
{
  Elf64_Xword result = 0;
  GElf_Ehdr h;
  ABG_ASSERT(gelf_getehdr(elf_handle, &h));
  int c;
  c = h.e_ident[EI_CLASS];
 
  switch(c)
    {
    case ELFCLASS32:
      result = bloom_filter[index];
      break ;
    case ELFCLASS64:
      {
    Elf64_Xword* f= reinterpret_cast<Elf64_Xword*>(bloom_filter);
    result = f[index];
      }
      break;
    default:
      abort();
    }
 
  return result;
}
 
/// The abstraction of the gnu elf hash table.
///
/// The members of this struct are explained at
///   - https://sourceware.org/ml/binutils/2006-10/msg00377.html
///   - https://blogs.oracle.com/ali/entry/gnu_hash_elf_sections.
struct gnu_ht
{
  size_t nb_buckets;
  Elf32_Word* buckets;
  Elf32_Word* chain;
  size_t first_sym_index;
  size_t bf_nwords;
  size_t bf_size;
  Elf32_Word* bloom_filter;
  size_t shift;
  size_t sym_count;
  Elf_Scn* sym_tab_section;
  GElf_Shdr sym_tab_section_header;
 
  gnu_ht()
    : nb_buckets(0),
      buckets(0),
      chain(0),
      first_sym_index(0),
      bf_nwords(0),
      bf_size(0),
      bloom_filter(0),
      shift(0),
      sym_count(0),
      sym_tab_section(0)
  {}
}; // end struct gnu_ht
 
/// Setup the members of the gnu hash table.
///
/// @param elf_handle a handle on the elf file to use.
///
/// @param ht_index the index  (into the elf section headers table) of
/// the hash table section to use.
///
/// @param sym_tab_index the index (into the elf section headers
/// table) of the symbol table the gnu hash table is about.
///
/// @param ht the resulting hash table.
///
/// @return true iff the hash table @ ht could be setup.
static bool
setup_gnu_ht(Elf* elf_handle,
         size_t ht_index,
         size_t sym_tab_index,
         gnu_ht& ht)
{
  ht.sym_tab_section = elf_getscn(elf_handle, sym_tab_index);
  ABG_ASSERT(ht.sym_tab_section);
  ABG_ASSERT(gelf_getshdr(ht.sym_tab_section, &ht.sym_tab_section_header));
  ht.sym_count =
    ht.sym_tab_section_header.sh_size / ht.sym_tab_section_header.sh_entsize;
  Elf_Scn* hash_section = elf_getscn(elf_handle, ht_index);
  ABG_ASSERT(hash_section);
 
  // Poke at the different parts of the hash table and get them ready
  // to be used.
  Elf_Data* ht_section_data = elf_getdata(hash_section, 0);
  Elf32_Word* ht_data = reinterpret_cast<Elf32_Word*>(ht_section_data->d_buf);
 
  ht.nb_buckets = ht_data[0];
  if (ht.nb_buckets == 0)
    // An empty hash table.  Not sure if that is possible, but it
    // would mean an empty table of exported symbols.
    return false;
  ht.first_sym_index = ht_data[1];
  // The number of words used by the bloom filter.  A size of a word
  // is ELFCLASS.
  ht.bf_nwords = ht_data[2];
  // The shift used by the bloom filter code.
  ht.shift = ht_data[3];
  // The data of the bloom filter proper.
  ht.bloom_filter = &ht_data[4];
  // The size of the bloom filter in 4 bytes word.  This is going to
  // be used to index the 'bloom_filter' above, which is of type
  // Elf32_Word*; thus we need that bf_size be expressed in 4 bytes
  // words.
  ht.bf_size = (get_elf_class_size_in_bytes(elf_handle) / 4) * ht.bf_nwords;
  // The buckets of the hash table.
  ht.buckets = ht.bloom_filter + ht.bf_size;
  // The chain of the hash table.
  ht.chain = ht.buckets + ht.nb_buckets;
 
  return true;
}
 
/// Look into the symbol tables of the underlying elf file and find
/// the symbol we are being asked.
///
/// This function uses the GNU hash table for the symbol lookup.
///
/// The reference of for the implementation of this function can be
/// found at:
///   - https://sourceware.org/ml/binutils/2006-10/msg00377.html
///   - https://blogs.oracle.com/ali/entry/gnu_hash_elf_sections.
///
/// @param elf_handle the elf handle to use.
///
/// @param sym_name the name of the symbol to look for.
///
/// @param ht_index the index of the hash table header to use.
///
/// @param sym_tab_index the index of the symbol table header to use
/// with this hash table.
///
/// @param demangle if true, demangle @p sym_name.
///
/// @param syms_found the vector of symbols found with the name @p
/// sym_name.
///
/// @return true if a symbol was actually found.
static bool
lookup_symbol_from_gnu_hash_tab(const environment&      env,
                Elf*                elf_handle,
                const string&           sym_name,
                size_t              ht_index,
                size_t              sym_tab_index,
                bool                demangle,
                vector<elf_symbol_sptr>&    syms_found)
{
  gnu_ht ht;
  if (!setup_gnu_ht(elf_handle, ht_index, sym_tab_index, ht))
    return false;
 
  // Now do the real work.
 
  // Compute bloom hashes (GNU hash and second bloom specific hashes).
  size_t h1 = elf_gnu_hash(sym_name.c_str());
  size_t h2 = h1 >> ht.shift;
  // The size of one of the words used in the bloom
  // filter, in bits.
  int c = get_elf_class_size_in_bytes(elf_handle) * 8;
  int n =  (h1 / c) % ht.bf_nwords;
  // The bitmask of the bloom filter has a size of either 32-bits on
  // ELFCLASS32 binaries or 64-bits on ELFCLASS64 binaries.  So we
  // need a 64-bits type to hold the bitmap, hence the Elf64_Xword
  // type used here.  When dealing with 32bits binaries, the upper
  // bits of the bitmask will be zero anyway.
  Elf64_Xword bitmask = (1ul << (h1 % c)) | (1ul << (h2 % c));
 
  // Test if the symbol is *NOT* present in this ELF file.
  if ((bloom_word_at(elf_handle, ht.bloom_filter, n) & bitmask) != bitmask)
    return false;
 
  size_t i = ht.buckets[h1 % ht.nb_buckets];
  if (i == STN_UNDEF)
    return false;
 
  Elf32_Word stop_word, *stop_wordp;
  elf_symbol::version ver;
  GElf_Sym symbol;
  const char* sym_name_str;
  bool found = false;
 
  elf_symbol::type sym_type;
  elf_symbol::binding sym_binding;
  elf_symbol::visibility sym_visibility;
 
  // Let's walk the hash table and record the versions of all the
  // symbols which name equal sym_name.
  for (i = ht.buckets[h1 % ht.nb_buckets],
     stop_wordp = &ht.chain[i - ht.first_sym_index];
       i != STN_UNDEF
     && (stop_wordp
         < ht.chain + (ht.sym_count - ht.first_sym_index));
       ++i, ++stop_wordp)
    {
      stop_word = *stop_wordp;
      if ((stop_word & ~ 1)!= (h1 & ~1))
    // A given bucket can reference several hashes.  Here we
    // stumbled across a hash value different from the one we are
    // looking for.  Let's keep walking.
    continue;
 
      ABG_ASSERT(gelf_getsym(elf_getdata(ht.sym_tab_section, 0),
             i, &symbol));
      sym_name_str = elf_strptr(elf_handle,
                ht.sym_tab_section_header.sh_link,
                symbol.st_name);
      if (sym_name_str
      && compare_symbol_name(sym_name_str, sym_name, demangle))
    {
      // So we found a symbol (in the symbol table) that equals
      // sym_name.  Now lets try to get its version and record it.
      sym_type = stt_to_elf_symbol_type(GELF_ST_TYPE(symbol.st_info));
      sym_binding = stb_to_elf_symbol_binding(GELF_ST_BIND(symbol.st_info));
     sym_visibility =
       stv_to_elf_symbol_visibility(GELF_ST_VISIBILITY(symbol.st_other));
 
      if (get_version_for_symbol(elf_handle, i,
                     /*get_def_version=*/true,
                     ver))
        ABG_ASSERT(!ver.str().empty());
 
      elf_symbol_sptr symbol_found =
        elf_symbol::create(env, i,
                   symbol.st_size,
                   sym_name_str,
                   sym_type, sym_binding,
                   symbol.st_shndx != SHN_UNDEF,
                   symbol.st_shndx == SHN_COMMON,
                   ver, sym_visibility);
      syms_found.push_back(symbol_found);
      found = true;
    }
 
      if (stop_word & 1)
    // The last bit of the stop_word is 1.  That means we need to
    // stop here.  We reached the end of the chain of values
    // referenced by the hask bucket.
    break;
    }
  return found;
}
 
/// Look into the symbol tables of the underlying elf file and find
/// the symbol we are being asked.
///
/// This function uses the elf hash table (be it the GNU hash table or
/// the sysv hash table) for the symbol lookup.
///
/// @param env the environment we are operating from.
///
/// @param elf_handle the elf handle to use.
///
/// @param ht_kind the kind of hash table to use.  This is returned by
/// the function function find_hash_table_section_index.
///
/// @param ht_index the index (in the section headers table) of the
/// hash table section to use.
///
/// @param sym_tab_index the index (in section headers table) of the
/// symbol table index to use with this hash table.
///
/// @param symbol_name the name of the symbol to look for.
///
/// @param demangle if true, demangle @p sym_name.
///
/// @param syms_found the symbols that were actually found with the
/// name @p symbol_name.
///
/// @return true iff the function found the symbol from the elf hash
/// table.
static bool
lookup_symbol_from_elf_hash_tab(const environment&      env,
                Elf*                elf_handle,
                hash_table_kind     ht_kind,
                size_t              ht_index,
                size_t              symtab_index,
                const string&           symbol_name,
                bool                demangle,
                vector<elf_symbol_sptr>&    syms_found)
{
  if (elf_handle == 0 || symbol_name.empty())
    return false;
 
  if (ht_kind == NO_HASH_TABLE_KIND)
    return false;
 
  if (ht_kind == SYSV_HASH_TABLE_KIND)
    return lookup_symbol_from_sysv_hash_tab(env,
                        elf_handle, symbol_name,
                        ht_index,
                        symtab_index,
                        demangle,
                        syms_found);
  else if (ht_kind == GNU_HASH_TABLE_KIND)
    return lookup_symbol_from_gnu_hash_tab(env,
                       elf_handle, symbol_name,
                       ht_index,
                       symtab_index,
                       demangle,
                       syms_found);
  return false;
}
 
/// Lookup a symbol from the symbol table directly.
///
///
/// @param env the environment we are operating from.
///
/// @param elf_handle the elf handle to use.
///
/// @param sym_name the name of the symbol to look up.
///
/// @param sym_tab_index the index (in the section headers table) of
/// the symbol table section.
///
/// @param demangle if true, demangle the names found in the symbol
/// table before comparing them with @p sym_name.
///
/// @param sym_name_found the actual name of the symbol found.
///
/// @param sym_type the type of the symbol found.
///
/// @param sym_binding the binding of the symbol found.
///
/// @param sym_versions the versions of the symbol found.
///
/// @return true iff the symbol was found.
static bool
lookup_symbol_from_symtab(const environment&        env,
              Elf*              elf_handle,
              const string&     sym_name,
              size_t            sym_tab_index,
              bool              demangle,
              vector<elf_symbol_sptr>&  syms_found)
{
  // TODO: read all of the symbol table, store it in memory in a data
  // structure that associates each symbol with its versions and in
  // which lookups of a given symbol is fast.
  Elf_Scn* sym_tab_section = elf_getscn(elf_handle, sym_tab_index);
  ABG_ASSERT(sym_tab_section);
 
  GElf_Shdr header_mem;
  GElf_Shdr * sym_tab_header = gelf_getshdr(sym_tab_section,
                        &header_mem);
 
  size_t symcount = sym_tab_header->sh_size / sym_tab_header->sh_entsize;
  Elf_Data* symtab = elf_getdata(sym_tab_section, NULL);
  GElf_Sym* sym;
  char* name_str = 0;
  elf_symbol::version ver;
  bool found = false;
 
  for (size_t i = 0; i < symcount; ++i)
    {
      GElf_Sym sym_mem;
      sym = gelf_getsym(symtab, i, &sym_mem);
      name_str = elf_strptr(elf_handle,
                sym_tab_header->sh_link,
                sym->st_name);
 
      if (name_str && compare_symbol_name(name_str, sym_name, demangle))
    {
      elf_symbol::type sym_type =
        stt_to_elf_symbol_type(GELF_ST_TYPE(sym->st_info));
      elf_symbol::binding sym_binding =
        stb_to_elf_symbol_binding(GELF_ST_BIND(sym->st_info));
      elf_symbol::visibility sym_visibility =
        stv_to_elf_symbol_visibility(GELF_ST_VISIBILITY(sym->st_other));
      bool sym_is_defined = sym->st_shndx != SHN_UNDEF;
      bool sym_is_common = sym->st_shndx == SHN_COMMON;
 
      if (get_version_for_symbol(elf_handle, i,
                     /*get_def_version=*/sym_is_defined,
                     ver))
        ABG_ASSERT(!ver.str().empty());
      elf_symbol_sptr symbol_found =
        elf_symbol::create(env, i, sym->st_size,
                   name_str, sym_type,
                   sym_binding, sym_is_defined,
                   sym_is_common, ver, sym_visibility);
      syms_found.push_back(symbol_found);
      found = true;
    }
    }
 
  if (found)
    return true;
 
  return false;
}
 
/// Look into the symbol tables of the underlying elf file and see
/// if we find a given symbol.
///
/// @param env the environment we are operating from.
///
/// @param symbol_name the name of the symbol to look for.
///
/// @param demangle if true, try to demangle the symbol name found in
/// the symbol table before comparing it to @p symbol_name.
///
/// @param syms_found the list of symbols found, with the name @p
/// symbol_name.
///
/// @param sym_type this is set to the type of the symbol found.  This
/// shall b a standard elf.h value for symbol types, that is SHT_OBJECT,
/// STT_FUNC, STT_IFUNC, etc ...
///
/// Note that this parameter is set iff the function returns true.
///
/// @param sym_binding this is set to the binding of the symbol found.
/// This is a standard elf.h value of the symbol binding kind, that
/// is, STB_LOCAL, STB_GLOBAL, or STB_WEAK.
///
/// @param symbol_versions the versions of the symbol @p symbol_name,
/// if it was found.
///
/// @return true iff a symbol with the name @p symbol_name was found.
static bool
lookup_symbol_from_elf(const environment&       env,
               Elf*             elf_handle,
               const string&            symbol_name,
               bool             demangle,
               vector<elf_symbol_sptr>& syms_found)
{
  size_t hash_table_index = 0, symbol_table_index = 0;
  hash_table_kind ht_kind = NO_HASH_TABLE_KIND;
 
  if (!demangle)
    ht_kind = find_hash_table_section_index(elf_handle,
                        hash_table_index,
                        symbol_table_index);
 
  if (ht_kind == NO_HASH_TABLE_KIND)
    {
      if (!find_symbol_table_section_index(elf_handle, symbol_table_index))
    return false;
 
      return lookup_symbol_from_symtab(env,
                       elf_handle,
                       symbol_name,
                       symbol_table_index,
                       demangle,
                       syms_found);
    }
 
  return lookup_symbol_from_elf_hash_tab(env,
                     elf_handle,
                     ht_kind,
                     hash_table_index,
                     symbol_table_index,
                     symbol_name,
                     demangle,
                     syms_found);
}
 
/// Look into the symbol tables of the underlying elf file and see if
/// we find a given public (global or weak) symbol of function type.
///
/// @param env the environment we are operating from.
///
/// @param elf_handle the elf handle to use for the query.
///
/// @param symbol_name the function symbol to look for.
///
/// @param func_syms the vector of public functions symbols found, if
/// any.
///
/// @return true iff the symbol was found.
static bool
lookup_public_function_symbol_from_elf(environment&         env,
                       Elf*             elf_handle,
                       const string&            symbol_name,
                       vector<elf_symbol_sptr>& func_syms)
{
  vector<elf_symbol_sptr> syms_found;
  bool found = false;
 
  if (lookup_symbol_from_elf(env, elf_handle, symbol_name,
                 /*demangle=*/false, syms_found))
    {
      for (vector<elf_symbol_sptr>::const_iterator i = syms_found.begin();
       i != syms_found.end();
       ++i)
    {
      elf_symbol::type type = (*i)->get_type();
      elf_symbol::binding binding = (*i)->get_binding();
 
      if ((type == elf_symbol::FUNC_TYPE
           || type == elf_symbol::GNU_IFUNC_TYPE
           || type == elf_symbol::COMMON_TYPE)
          && (binding == elf_symbol::GLOBAL_BINDING
          || binding == elf_symbol::WEAK_BINDING))
        {
          func_syms.push_back(*i);
          found = true;
        }
    }
    }
 
  return found;
}
 
// ---------------------------------------
// <location expression evaluation types>
// ---------------------------------------
 
/// An abstraction of a value representing the result of the
/// evaluation of a dwarf expression.  This is abstraction represents
/// a partial view on the possible values because we are only
/// interested in extracting the latest and longuest constant
/// sub-expression of a given dwarf expression.
class expr_result
{
  bool is_const_;
  int64_t const_value_;
 
public:
  expr_result()
    : is_const_(true),
      const_value_(0)
  {}
 
  expr_result(bool is_const)
    : is_const_(is_const),
      const_value_(0)
  {}
 
  explicit expr_result(int64_t v)
    :is_const_(true),
     const_value_(v)
  {}
 
  /// @return true if the value is a constant.  Otherwise, return
  /// false, meaning the value represents a quantity for which we need
  /// inferior (a running program) state to determine the value.
  bool
  is_const() const
  {return is_const_;}
 
 
  /// @param f a flag saying if the value is set to a constant or not.
  void
  is_const(bool f)
  {is_const_ = f;}
 
  /// Get the current constant value iff this represents a
  /// constant.
  ///
  /// @param value the out parameter.  Is set to the constant value of
  /// the @ref expr_result.  This is set iff the function return true.
  ///
  ///@return true if this has a constant value, false otherwise.
  bool
  const_value(int64_t& value)
  {
    if (is_const())
      {
    value = const_value_;
    return true;
      }
    return false;
  }
 
  /// Getter of the constant value of the current @ref expr_result.
  ///
  /// Note that the current @ref expr_result must be constant,
  /// otherwise the current process is aborted.
  ///
  /// @return the constant value of the current @ref expr_result.
  int64_t
  const_value() const
  {
    ABG_ASSERT(is_const());
    return const_value_;
  }
 
  operator int64_t() const
  {return const_value();}
 
  expr_result&
  operator=(const int64_t v)
  {
    const_value_ = v;
    return *this;
  }
 
  bool
  operator==(const expr_result& o) const
  {return const_value_ == o.const_value_ && is_const_ == o.is_const_;}
 
  bool
  operator>=(const expr_result& o) const
  {return const_value_ >= o.const_value_;}
 
  bool
  operator<=(const expr_result& o) const
  {return const_value_ <= o.const_value_;}
 
  bool
  operator>(const expr_result& o) const
  {return const_value_ > o.const_value_;}
 
  bool
  operator<(const expr_result& o) const
  {return const_value_ < o.const_value_;}
 
  expr_result
  operator+(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ += v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const_;
    return r;
  }
 
  expr_result&
  operator+=(int64_t v)
  {
    const_value_ += v;
    return *this;
  }
 
  expr_result
  operator-(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ -= v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const_;
    return r;
  }
 
  expr_result
  operator%(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ %= v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const();
    return r;
  }
 
  expr_result
  operator*(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ *= v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const();
    return r;
  }
 
  expr_result
  operator|(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ |= v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const_;
    return r;
  }
 
  expr_result
  operator^(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ ^= v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const_;
    return r;
  }
 
  expr_result
  operator>>(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ = r.const_value_ >> v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const_;
    return r;
  }
 
  expr_result
  operator<<(const expr_result& v) const
  {
    expr_result r(*this);
    r.const_value_ = r.const_value_ << v.const_value_;
    r.is_const_ = r.is_const_ && v.is_const_;
    return r;
  }
 
  expr_result
  operator~() const
  {
    expr_result r(*this);
    r.const_value_ = ~r.const_value_;
    return r;
  }
 
  expr_result
  neg() const
  {
    expr_result r(*this);
    r.const_value_ = -r.const_value_;
    return r;
  }
 
  expr_result
  abs() const
  {
    expr_result r = *this;
    r.const_value_ = std::abs(static_cast<long double>(r.const_value()));
    return r;
  }
 
  expr_result
  operator&(const expr_result& o)
  {
    expr_result r(*this);
    r.const_value_ &= o.const_value_;
    r.is_const_ = r.is_const_ && o.is_const_;
    return r;
  }
 
  expr_result
  operator/(const expr_result& o)
  {
    expr_result r(*this);
    r.is_const_ = r.is_const_ && o.is_const_;
    return r.const_value() / o.const_value();
  }
};// class end expr_result;
 
/// A class that implements a stack of @ref expr_result, to be used in
/// the engine evaluating DWARF expressions.
class expr_result_stack_type
{
  vector<expr_result> elems_;
 
public:
 
  expr_result_stack_type()
  {elems_.reserve(4);}
 
  expr_result&
  operator[](unsigned i)
  {
    unsigned s = elems_.size();
    ABG_ASSERT(s > i);
    return elems_[s - 1 -i];
  }
 
  const expr_result&
  operator[](unsigned i) const
  {return const_cast<expr_result_stack_type*>(this)->operator[](i);}
 
  unsigned
  size() const
  {return elems_.size();}
 
  vector<expr_result>::reverse_iterator
  begin()
  {return elems_.rbegin();}
 
  const vector<expr_result>::reverse_iterator
  begin() const
  {return const_cast<expr_result_stack_type*>(this)->begin();}
 
  vector<expr_result>::reverse_iterator
  end()
  {return elems_.rend();}
 
  const vector<expr_result>::reverse_iterator
  end() const
  {return const_cast<expr_result_stack_type*>(this)->end();}
 
  expr_result&
  front()
  {return elems_.back();}
 
  const expr_result&
  front() const
  {return const_cast<expr_result_stack_type*>(this)->front();}
 
  void
  push_front(expr_result e)
  {elems_.push_back(e);}
 
  expr_result
  pop_front()
  {
    expr_result r = front();
    elems_.pop_back();
    return r;
  }
 
  void
  erase(vector<expr_result>::reverse_iterator i)
  {elems_.erase(--i.base());}
 
  void
  clear()
  {elems_.clear();}
}; // end class expr_result_stack_type
 
/// Abstraction of the evaluation context of a dwarf expression.
struct dwarf_expr_eval_context
{
  expr_result accum;
  expr_result_stack_type stack;
  // Is set to true if the result of the expression that got evaluated
  // is a TLS address.
  bool set_tls_addr;
 
  dwarf_expr_eval_context()
    : accum(/*is_const=*/false),
      set_tls_addr(false)
  {
    stack.push_front(expr_result(true));
  }
 
  void
  reset()
  {
    stack.clear();
    stack.push_front(expr_result(true));
    accum = expr_result(false);
    set_tls_addr = false;
  }
 
  /// Set a flag to to tell that the result of the expression that got
  /// evaluated is a TLS address.
  ///
  /// @param f true iff the result of the expression that got
  /// evaluated is a TLS address, false otherwise.
  void
  set_tls_address(bool f)
  {set_tls_addr = f;}
 
  /// Getter for the flag that tells if the result of the expression
  /// that got evaluated is a TLS address.
  ///
  /// @return true iff the result of the expression that got evaluated
  /// is a TLS address.
  bool
  set_tls_address() const
  {return set_tls_addr;}
 
  expr_result
  pop()
  {
    expr_result r = stack.front();
    stack.pop_front();
    return r;
  }
 
  void
  push(const expr_result& v)
  {stack.push_front(v);}
};//end class dwarf_expr_eval_context
 
// ---------------------------------------
// </location expression evaluation types>
// ---------------------------------------
 
class reader;
 
typedef shared_ptr<reader> reader_sptr;
 
/// The DWARF reader used to build the ABI corpus from debug info in
/// DWARF format.
///
/// This type is to be instanciated
/// abigail::dwarf::reader::create().
class reader : public elf_based_reader
{
public:
 
  /// A set of containers that contains one container per kind of @ref
  /// die_source.  This allows to associate DIEs to things, depending
  /// on the source of the DIE.
  template <typename ContainerType>
  class die_source_dependant_container_set
  {
    ContainerType primary_debug_info_container_;
    ContainerType alt_debug_info_container_;
    ContainerType type_unit_container_;
 
  public:
 
    /// Getter for the container associated to DIEs coming from a
    /// given @ref die_source.
    ///
    /// @param source the die_source for which we want the container.
    ///
    /// @return the container that associates DIEs coming from @p
    /// source to something.
    ContainerType&
    get_container(die_source source)
    {
      ContainerType *result = 0;
      switch (source)
    {
    case PRIMARY_DEBUG_INFO_DIE_SOURCE:
      result = &primary_debug_info_container_;
      break;
    case ALT_DEBUG_INFO_DIE_SOURCE:
      result = &alt_debug_info_container_;
      break;
    case TYPE_UNIT_DIE_SOURCE:
      result = &type_unit_container_;
      break;
    case NO_DEBUG_INFO_DIE_SOURCE:
    case NUMBER_OF_DIE_SOURCES:
      ABG_ASSERT_NOT_REACHED;
    }
      return *result;
    }
 
    /// Getter for the container associated to DIEs coming from a
    /// given @ref die_source.
    ///
    /// @param source the die_source for which we want the container.
    ///
    /// @return the container that associates DIEs coming from @p
    /// source to something.
    const ContainerType&
    get_container(die_source source) const
    {
      return const_cast<die_source_dependant_container_set*>(this)->
    get_container(source);
    }
 
    /// Getter for the container associated to DIEs coming from the
    /// same source as a given DIE.
    ///
    /// @param rdr the DWARF reader to consider.
    ///
    /// @param die the DIE which should have the same source as the
    /// source of the container we want.
    ///
    /// @return the container that associates DIEs coming from the
    /// same source as @p die.
    ContainerType&
    get_container(const reader& rdr, const Dwarf_Die *die)
    {
      const die_source source = rdr.get_die_source(die);
      return get_container(source);
    }
 
    /// Getter for the container associated to DIEs coming from the
    /// same source as a given DIE.
    ///
    /// @param rdr the DWARF reader to consider.
    ///
    /// @param die the DIE which should have the same source as the
    /// source of the container we want.
    ///
    /// @return the container that associates DIEs coming from the
    /// same source as @p die.
    const ContainerType&
    get_container(const reader& rdr, const Dwarf_Die *die) const
    {
      return const_cast<die_source_dependant_container_set*>(this)->
    get_container(rdr, die);
    }
 
    /// Clear the container set.
    void
    clear()
    {
      primary_debug_info_container_.clear();
      alt_debug_info_container_.clear();
      type_unit_container_.clear();
    }
  }; // end die_dependant_container_set
 
  unsigned short        dwarf_version_;
  Dwarf_Die*            cur_tu_die_;
  mutable dwarf_expr_eval_context   dwarf_expr_eval_context_;
  // A set of maps (one per kind of die source) that associates a decl
  // string representation with the DIEs (offsets) representing that
  // decl.
  mutable die_source_dependant_container_set<istring_dwarf_offsets_map_type>
  decl_die_repr_die_offsets_maps_;
  // A set of maps (one per kind of die source) that associates a type
  // string representation with the DIEs (offsets) representing that
  // type.
  mutable die_source_dependant_container_set<istring_dwarf_offsets_map_type>
  type_die_repr_die_offsets_maps_;
  mutable die_source_dependant_container_set<die_istring_map_type>
  die_qualified_name_maps_;
  mutable die_source_dependant_container_set<die_istring_map_type>
  die_pretty_repr_maps_;
  mutable die_source_dependant_container_set<die_istring_map_type>
  die_pretty_type_repr_maps_;
  // A set of maps (one per kind of die source) that associates the
  // offset of a decl die to its corresponding decl artifact.
  mutable die_source_dependant_container_set<die_artefact_map_type>
  decl_die_artefact_maps_;
  // A set of maps (one per kind of die source) that associates the
  // offset of a type die to its corresponding type artifact.
  mutable die_source_dependant_container_set<die_artefact_map_type>
  type_die_artefact_maps_;
  /// A set of vectors (one per kind of die source) that associates
  /// the offset of a type DIE to the offset of its canonical DIE.
  mutable die_source_dependant_container_set<offset_offset_map_type>
  canonical_type_die_offsets_;
  /// A set of vectors (one per kind of die source) that associates
  /// the offset of a decl DIE to the offset of its canonical DIE.
  mutable die_source_dependant_container_set<offset_offset_map_type>
  canonical_decl_die_offsets_;
  /// A map that associates a function type representations to
  /// function types, inside a translation unit.
  mutable istring_fn_type_map_type per_tu_repr_to_fn_type_maps_;
  /// A map that associates a pair of DIE offsets to the result of the
  /// comparison of that pair.
  mutable std::unordered_map<std::pair<offset_type,offset_type>,
                 abigail::ir::comparison_result,
                 dwarf_offset_pair_hash> die_comparison_results_;
  // The set of types pair that have been canonical-type-propagated.
  mutable offset_pair_set_type propagated_types_;
  die_class_or_union_map_type   die_wip_classes_map_;
  die_class_or_union_map_type   alternate_die_wip_classes_map_;
  die_class_or_union_map_type   type_unit_die_wip_classes_map_;
  die_function_type_map_type    die_wip_function_types_map_;
  die_function_type_map_type    alternate_die_wip_function_types_map_;
  die_function_type_map_type    type_unit_die_wip_function_types_map_;
  die_function_decl_map_type    die_function_with_no_symbol_map_;
  vector<type_base_sptr>    types_to_canonicalize_;
  string_classes_or_unions_map  decl_only_classes_map_;
  string_enums_map      decl_only_enums_map_;
  die_tu_map_type       die_tu_map_;
  translation_unit_sptr cur_tu_;
  scope_decl_sptr       nil_scope_;
  scope_stack_type      scope_stack_;
  offset_offset_map_type    primary_die_parent_map_;
  // A map that associates each tu die to a vector of unit import
  // points, in the main debug info
  tu_die_imported_unit_points_map_type tu_die_imported_unit_points_map_;
  // A map that associates each tu die to a vector of unit import
  // points, in the alternate debug info
  tu_die_imported_unit_points_map_type alt_tu_die_imported_unit_points_map_;
  tu_die_imported_unit_points_map_type type_units_tu_die_imported_unit_points_map_;
  // A DIE -> parent map for DIEs coming from the alternate debug info
  // file.
  offset_offset_map_type    alternate_die_parent_map_;
  offset_offset_map_type    type_section_die_parent_map_;
  list<var_decl_sptr>       var_decls_to_add_;
#ifdef WITH_DEBUG_TYPE_CANONICALIZATION
  bool              debug_die_canonicalization_is_on_;
  bool              use_canonical_die_comparison_;
#endif
  mutable size_t        compare_count_;
  mutable size_t        canonical_propagated_count_;
  mutable size_t        cancelled_propagation_count_;
  mutable optional<bool>    leverage_dwarf_factorization_;
 
protected:
 
  reader() = delete;
 
  /// Constructor of reader.
  ///
  /// @param elf_path the path to the elf file the context is to be
  /// used for.
  ///
  /// @param debug_info_root_paths a vector of pointers to the path to
  /// the root directory under which the debug info is to be found for
  /// @p elf_path.  Leave this empty if the debug info is not in a
  /// split file.
  ///
  /// @param environment the environment used by the current context.
  /// This environment contains resources needed by the DWARF reader and by
  /// the types and declarations that are to be created later.  Note
  /// that ABI artifacts that are to be compared all need to be
  /// created within the same environment.
  ///
  /// Please also note that the life time of this environment object
  /// must be greater than the life time of the resulting @ref
  /// reader the context uses resources that are allocated in
  /// the environment.
  ///
  /// @param load_all_types if set to false only the types that are
  /// reachable from publicly exported declarations (of functions and
  /// variables) are read.  If set to true then all types found in the
  /// debug information are loaded.
  ///
  /// @param linux_kernel_mode if set to true, then consider the special
  /// linux kernel symbol tables when determining if a symbol is
  /// exported or not.
  reader(const string&      elf_path,
     const vector<char**>&  debug_info_root_paths,
     environment&       environment,
     bool           load_all_types,
     bool           linux_kernel_mode)
    : elf_based_reader(elf_path,
               debug_info_root_paths,
               environment)
  {
    initialize(load_all_types, linux_kernel_mode);
  }
 
public:
 
  /// Initializer of reader.
  ///
  /// Resets the reader so that it can be re-used to read another binary.
  ///
  /// @param load_all_types if set to false only the types that are
  /// reachable from publicly exported declarations (of functions and
  /// variables) are read.  If set to true then all types found in the
  /// debug information are loaded.
  ///
  /// @param linux_kernel_mode if set to true, then consider the
  /// special linux kernel symbol tables when determining if a symbol
  /// is exported or not.
  void
  initialize(bool load_all_types, bool linux_kernel_mode)
  {
    dwarf_version_ = 0;
    cur_tu_die_ =  0;
    decl_die_repr_die_offsets_maps_.clear();
    type_die_repr_die_offsets_maps_.clear();
    die_qualified_name_maps_.clear();
    die_pretty_repr_maps_.clear();
    die_pretty_type_repr_maps_.clear();
    decl_die_artefact_maps_.clear();
    type_die_artefact_maps_.clear();
    canonical_type_die_offsets_.clear();
    canonical_decl_die_offsets_.clear();
    die_wip_classes_map_.clear();
    alternate_die_wip_classes_map_.clear();
    type_unit_die_wip_classes_map_.clear();
    die_wip_function_types_map_.clear();
    alternate_die_wip_function_types_map_.clear();
    type_unit_die_wip_function_types_map_.clear();
    die_function_with_no_symbol_map_.clear();
    types_to_canonicalize_.clear();
    decl_only_classes_map_.clear();
    die_tu_map_.clear();
    corpus().reset();
    corpus_group().reset();
    cur_tu_.reset();
    primary_die_parent_map_.clear();
    tu_die_imported_unit_points_map_.clear();
    alt_tu_die_imported_unit_points_map_.clear();
    type_units_tu_die_imported_unit_points_map_.clear();
    alternate_die_parent_map_.clear();
    type_section_die_parent_map_.clear();
    var_decls_to_add_.clear();
    clear_per_translation_unit_data();
    options().load_in_linux_kernel_mode = linux_kernel_mode;
    options().load_all_types = load_all_types;
#ifdef WITH_DEBUG_TYPE_CANONICALIZATION
    debug_die_canonicalization_is_on_ =
      env().debug_die_canonicalization_is_on();
    use_canonical_die_comparison_ = true;
#endif
    compare_count_ = 0;
    canonical_propagated_count_ = 0;
    cancelled_propagation_count_ = 0;
    load_in_linux_kernel_mode(linux_kernel_mode);
  }
 
    /// Initializer of reader.
  ///
  /// Resets the reader so that it can be re-used to read another binary.
  ///
  /// @param elf_path the path to the new ELF file.
  ///
  /// @param debug_info_root_paths the vector of debug-info path to
  /// look for split debug info.
  ///
  /// @param load_all_types if set to false only the types that are
  /// reachable from publicly exported declarations (of functions and
  /// variables) are read.  If set to true then all types found in the
  /// debug information are loaded.
  ///
  /// @param linux_kernel_mode if set to true, then consider the
  /// special linux kernel symbol tables when determining if a symbol
  /// is exported or not.
  void
  initialize(const string&      elf_path,
         const vector<char**>&  debug_info_root_paths,
         bool           load_all_types,
         bool           linux_kernel_mode)
  {
    reset(elf_path, debug_info_root_paths);
    initialize(load_all_types, linux_kernel_mode);
  }
 
  /// Create an instance of DWARF Reader.
  ///
  /// @param elf_path the path to the ELF file to read from.
  ///
  /// @param debug_info_root_paths a vector of paths where to look up
  /// split debug info files.
  ///
  /// @param environment the environment to be used by the reader.
  ///
  /// @param load_all_types if set to false only the types that are
  /// reachable from publicly exported declarations (of functions and
  /// variables) are read.  If set to true then all types found in the
  /// debug information are loaded.
  ///
  /// @param linux_kernel_mode if set to true, then consider the
  /// special linux kernel symbol tables when determining if a symbol
  /// is exported or not.
  static dwarf::reader_sptr
  create(const std::string& elf_path,
     const vector<char**>&  debug_info_root_paths,
     environment&       environment,
     bool           load_all_types,
     bool           linux_kernel_mode)
  {
    reader_sptr result(new reader(elf_path, debug_info_root_paths,
                  environment, load_all_types,
                  linux_kernel_mode));
    return result;
  }
 
  /// Destructor of the @ref reader type.
  ~reader()
  {
  }
 
  /// Read and analyze the ELF and DWARF information associated with
  /// the underlying ELF file and build an ABI corpus out of it.
  ///
  /// @param status output parameter.  This is set to the status of
  /// the analysis of the debug info.
  ///
  /// @return the resulting ABI corpus.
  corpus_sptr
  read_corpus(status& status)
  {
    status = STATUS_UNKNOWN;
 
    // Load the generic ELF parts of the corpus.
    elf::reader::read_corpus(status);
 
    if ((status & STATUS_NO_SYMBOLS_FOUND)
    || !(status & STATUS_OK))
      // Either we couldn't find ELF symbols or something went badly
      // wrong.  There is nothing we can do with this ELF file.  Bail
      // out.
      return corpus_sptr();
 
    // If we couldn't find debug info from the elf path, then say it.
    if (dwarf_debug_info() == nullptr)
      status |= STATUS_DEBUG_INFO_NOT_FOUND;
 
    {
      string alt_di_path;
      if (refers_to_alt_debug_info(alt_di_path)
      && !alternate_dwarf_debug_info())
    status |= STATUS_ALT_DEBUG_INFO_NOT_FOUND;
    }
 
    if (// If debug info was found but not the required alternate debug
    // info ...
    ((status & STATUS_ALT_DEBUG_INFO_NOT_FOUND)
     && !(status & STATUS_DEBUG_INFO_NOT_FOUND)))
      // ... then we cannot handle the binary.
      return corpus_sptr();
 
    // Read the variable and function descriptions from the debug info
    // we have, through the dwfl handle.
    corpus_sptr corp = read_debug_info_into_corpus();
 
    status |= STATUS_OK;
 
    return corp;
  }
 
  /// Read an analyze the DWARF information.
  ///
  /// Construct an ABI corpus from it.
  ///
  /// This is a sub-routine of abigail::dwarf::reader::read_corpus().
  ///
  /// @return the resulting ABI corpus.
  corpus_sptr
  read_debug_info_into_corpus()
  {
    clear_per_corpus_data();
 
    // First set some mundane properties of the corpus gathered from
    // ELF.
    corpus::origin origin = corpus()->get_origin();
    origin |= corpus::DWARF_ORIGIN;
    corpus()->set_origin(origin);
 
    if (origin & corpus::LINUX_KERNEL_BINARY_ORIGIN
    && !env().user_set_analyze_exported_interfaces_only())
      // So we are looking at the Linux Kernel and the user has not set
      // any particular option regarding the amount of types to analyse.
      // In that case, we need to only analyze types that are reachable
      // from exported interfaces otherwise we get such a massive amount
      // of type DIEs to look at that things are just too slow down the
      // road.
      env().analyze_exported_interfaces_only(true);
 
    corpus()->set_soname(dt_soname());
    corpus()->set_needed(dt_needed());
    corpus()->set_architecture_name(elf_architecture());
    // Set symbols information to the corpus.
    corpus()->set_symtab(symtab());
 
    // Get out now if no debug info is found or if the symbol table is
    // empty.
    if (!dwarf_debug_info()
    || !corpus()->get_symtab()->has_symbols())
      return corpus();
 
    uint8_t address_size = 0;
    size_t header_size = 0;
 
#ifdef WITH_DEBUG_SELF_COMPARISON
    if (env().self_comparison_debug_is_on())
      env().set_self_comparison_debug_input(corpus());
#endif
 
    // Walk all the DIEs of the debug info to build a DIE -> parent map
    // useful for get_die_parent() to work.
    {
      tools_utils::timer t;
      if (do_log())
    {
      cerr << "building die -> parent maps ...";
      t.start();
    }
 
      build_die_parent_maps();
 
      if (do_log())
    {
      t.stop();
      cerr << " DONE@" << corpus()->get_path()
           << ":"
           << t
           << "\n";
    }
    }
 
    env().canonicalization_is_done(false);
 
    {
      tools_utils::timer t;
      if (do_log())
    {
      cerr << "building the libabigail internal representation ...";
      t.start();
    }
      // And now walk all the DIEs again to build the libabigail IR.
      Dwarf_Half dwarf_vers = 0;
      for (Dwarf_Off offset = 0, next_offset = 0;
       (dwarf_next_unit(const_cast<Dwarf*>(dwarf_debug_info()),
                offset, &next_offset, &header_size,
                &dwarf_vers, NULL, &address_size, NULL,
                NULL, NULL) == 0);
       offset = next_offset)
    {
      Dwarf_Off die_offset = offset + header_size;
      Dwarf_Die unit;
      if (!dwarf_offdie(const_cast<Dwarf*>(dwarf_debug_info()),
                die_offset, &unit)
          || dwarf_tag(&unit) != DW_TAG_compile_unit)
        continue;
 
      dwarf_version(dwarf_vers);
 
      address_size *= 8;
 
      // Build a translation_unit IR node from cu; note that cu must
      // be a DW_TAG_compile_unit die.
      translation_unit_sptr ir_node =
        build_translation_unit_and_add_to_ir(*this, &unit, address_size);
      ABG_ASSERT(ir_node);
    }
      if (do_log())
    {
      t.stop();
      cerr << " DONE@" << corpus()->get_path()
           << ":"
           << t
           << "\n";
 
      cerr << "Number of aggregate types compared: "
           << compare_count_ << "\n"
           << "Number of canonical types propagated: "
           << canonical_propagated_count_ << "\n"
           << "Number of cancelled propagated canonical types:"
           << cancelled_propagation_count_ << "\n";
    }
    }
 
    {
      tools_utils::timer t;
      if (do_log())
    {
      cerr << "resolving declaration only classes ...";
      t.start();
    }
      resolve_declaration_only_classes();
      if (do_log())
    {
      t.stop();
      cerr << " DONE@" << corpus()->get_path()
           << ":"
           << t
           <<"\n";
    }
    }
 
    {
      tools_utils::timer t;
      if (do_log())
    {
      cerr << "resolving declaration only enums ...";
      t.start();
    }
      resolve_declaration_only_enums();
      if (do_log())
    {
      t.stop();
      cerr << " DONE@" << corpus()->get_path()
           << ":"
           << t
           <<"\n";
    }
    }
 
    {
      tools_utils::timer t;
      if (do_log())
    {
      cerr << "fixing up functions with linkage name but "
           << "no advertised underlying symbols ....";
      t.start();
    }
      fixup_functions_with_no_symbols();
      if (do_log())
    {
      t.stop();
      cerr << " DONE@" << corpus()->get_path()
           <<":"
           << t
           <<"\n";
    }
    }
 
    /// Now, look at the types that needs to be canonicalized after the
    /// translation has been constructed (which is just now) and
    /// canonicalize them.
    ///
    /// These types need to be constructed at the end of the translation
    /// unit reading phase because some types are modified by some DIEs
    /// even after the principal DIE describing the type has been read;
    /// this happens for clones of virtual destructors (for instance) or
    /// even for some static data members.  We need to do that for types
    /// are in the alternate debug info section and for types that in
    /// the main debug info section.
    {
      tools_utils::timer t;
      if (do_log())
    {
      cerr << "perform late type canonicalizing ...\n";
      t.start();
    }
 
      perform_late_type_canonicalizing();
      if (do_log())
    {
      t.stop();
      cerr << "late type canonicalizing DONE@"
           << corpus()->get_path()
           << ":"
           << t
           << "\n";
    }
    }
 
    env().canonicalization_is_done(true);
 
    {
      tools_utils::timer t;
      if (do_log())
    {
      cerr << "sort functions and variables ...";
      t.start();
    }
      corpus()->sort_functions();
      corpus()->sort_variables();
      if (do_log())
    {
      t.stop();
      cerr << " DONE@" << corpus()->get_path()
           << ":"
           << t
           <<" \n";
    }
    }
 
    return corpus();
  }
 
  /// Clear the data that is relevant only for the current translation
  /// unit being read.  The rest of the data is relevant for the
  /// entire ABI corpus.
  void
  clear_per_translation_unit_data()
  {
    while (!scope_stack().empty())
      scope_stack().pop();
    var_decls_to_re_add_to_tree().clear();
    per_tu_repr_to_fn_type_maps().clear();
  }
 
  /// Clear the data that is relevant for the current corpus being
  /// read.
  void
  clear_per_corpus_data()
  {
    die_qualified_name_maps_.clear();
    die_pretty_repr_maps_.clear();
    die_pretty_type_repr_maps_.clear();
    clear_types_to_canonicalize();
  }
 
  /// Getter for the current environment.
  ///
  /// @return the current environment.
  environment&
  env()
  {return options().env;}
 
  /// Getter for the current environment.
  ///
  /// @return the current environment.
  const environment&
  env() const
  {return const_cast<reader*>(this)->env();}
 
  /// Getter for the flag that tells us if we are dropping functions
  /// and variables that have undefined symbols.
  ///
  /// @return true iff we are dropping functions and variables that have
  /// undefined symbols.
  bool
  drop_undefined_syms() const
  {return options().drop_undefined_syms;}
 
  /// Setter for the flag that tells us if we are dropping functions
  /// and variables that have undefined symbols.
  ///
  /// @param f the new value of the flag.
  void
  drop_undefined_syms(bool f)
  {options().drop_undefined_syms = f;}
 
  /// Getter of the DWARF version.
  unsigned short
  dwarf_version() const
  {return dwarf_version_;}
 
  void
  dwarf_version(unsigned short v)
  {dwarf_version_ = v;}
 
  /// Return the ELF descriptor used for DWARF access.
  ///
  /// This can be the same as reader::elf_handle() above, if the
  /// DWARF info is in the same ELF file as the one of the binary we
  /// are analizing.  It is different if e.g, the debug info is split
  /// from the ELF file we are analizing.
  ///
  /// @return a pointer to the ELF descriptor used to access debug
  /// info.
  Elf*
  dwarf_elf_handle() const
  {return dwarf_getelf(const_cast<Dwarf*>(dwarf_debug_info()));}
 
  /// Test if the debug information is in a separate ELF file wrt the
  /// main ELF file of the program (application or shared library) we
  /// are analizing.
  ///
  /// @return true if the debug information is in a separate ELF file
  /// compared to the main ELF file of the program (application or
  /// shared library) that we are looking at.
  bool
  dwarf_is_splitted() const
  {return dwarf_elf_handle() != elf_handle();}
 
  /// Return the correct debug info, depending on the DIE source we
  /// are looking at.
  ///
  /// @param source the DIE source to consider.
  ///
  /// @return the right debug info, depending on @p source.
  const Dwarf*
  dwarf_per_die_source(die_source source) const
  {
    const Dwarf *result = 0;
    switch(source)
      {
      case PRIMARY_DEBUG_INFO_DIE_SOURCE:
      case TYPE_UNIT_DIE_SOURCE:
    result = dwarf_debug_info();
    break;
      case ALT_DEBUG_INFO_DIE_SOURCE:
    result = alternate_dwarf_debug_info();
    break;
      case NO_DEBUG_INFO_DIE_SOURCE:
      case NUMBER_OF_DIE_SOURCES:
    ABG_ASSERT_NOT_REACHED;
      }
    return result;
  }
 
  /// Return the path to the ELF path we are reading.
  ///
  /// @return the elf path.
  const string&
  elf_path() const
  {return corpus_path();}
 
  const Dwarf_Die*
  cur_tu_die() const
  {return cur_tu_die_;}
 
  void
  cur_tu_die(Dwarf_Die* cur_tu_die)
  {cur_tu_die_ = cur_tu_die;}
 
  dwarf_expr_eval_context&
  dwarf_expr_eval_ctxt() const
  {return dwarf_expr_eval_context_;}
 
  /// Getter of the maps set that associates a representation of a
  /// decl DIE to a vector of offsets of DIEs having that representation.
  ///
  /// @return the maps set that associates a representation of a decl
  /// DIE to a vector of offsets of DIEs having that representation.
  const die_source_dependant_container_set<istring_dwarf_offsets_map_type>&
  decl_die_repr_die_offsets_maps() const
  {return decl_die_repr_die_offsets_maps_;}
 
  /// Getter of the maps set that associates a representation of a
  /// decl DIE to a vector of offsets of DIEs having that representation.
  ///
  /// @return the maps set that associates a representation of a decl
  /// DIE to a vector of offsets of DIEs having that representation.
  die_source_dependant_container_set<istring_dwarf_offsets_map_type>&
  decl_die_repr_die_offsets_maps()
  {return decl_die_repr_die_offsets_maps_;}
 
  /// Getter of the maps set that associate a representation of a type
  /// DIE to a vector of offsets of DIEs having that representation.
  ///
  /// @return the maps set that associate a representation of a type
  /// DIE to a vector of offsets of DIEs having that representation.
  const die_source_dependant_container_set<istring_dwarf_offsets_map_type>&
  type_die_repr_die_offsets_maps() const
  {return type_die_repr_die_offsets_maps_;}
 
  /// Getter of the maps set that associate a representation of a type
  /// DIE to a vector of offsets of DIEs having that representation.
  ///
  /// @return the maps set that associate a representation of a type
  /// DIE to a vector of offsets of DIEs having that representation.
  die_source_dependant_container_set<istring_dwarf_offsets_map_type>&
  type_die_repr_die_offsets_maps()
  {return type_die_repr_die_offsets_maps_;}
 
 
  /// Compute the offset of the canonical DIE of a given DIE.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param canonical_die_offset out parameter.  This is set to the
  /// resulting canonical DIE that was computed.
  ///
  /// @param die_as_type if yes, it means @p die has to be considered
  /// as a type.
  void
  compute_canonical_die_offset(const Dwarf_Die *die,
                   Dwarf_Off &canonical_die_offset,
                   bool die_as_type) const
  {
    offset_offset_map_type &canonical_dies =
      die_as_type
      ? const_cast<reader*>(this)->canonical_type_die_offsets_.
      get_container(*this, die)
      : const_cast<reader*>(this)->canonical_decl_die_offsets_.
      get_container(*this, die);
 
    Dwarf_Die canonical_die;
    compute_canonical_die(die, canonical_dies, canonical_die, die_as_type);
 
    canonical_die_offset = dwarf_dieoffset(&canonical_die);
  }
 
  /// Compute (find) the canonical DIE of a given DIE.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param canonical_dies the vector in which the canonical dies ar
  /// stored.  The index of each element is the offset of the DIE we
  /// want the canonical DIE for.  And the value of the element at
  /// that index is the canonical DIE offset we are looking for.
  ///
  /// @param canonical_die_offset out parameter.  This is set to the
  /// resulting canonical DIE that was computed.
  ///
  /// @param die_as_type if yes, it means @p die has to be considered
  /// as a type.
  void
  compute_canonical_die(const Dwarf_Die *die,
            offset_offset_map_type& canonical_dies,
            Dwarf_Die &canonical_die,
            bool die_as_type) const
  {
    const die_source source = get_die_source(die);
 
    Dwarf_Off die_offset = dwarf_dieoffset(const_cast<Dwarf_Die*>(die));
 
    compute_canonical_die(die_offset, source,
              canonical_dies,
              canonical_die, die_as_type);
  }
 
  /// Compute (find) the canonical DIE of a given DIE.
  ///
  /// @param die_offset the offset of the DIE to consider.
  ///
  /// @param source the source of the DIE to consider.
  ///
  /// @param canonical_dies the vector in which the canonical dies ar
  /// stored.  The index of each element is the offset of the DIE we
  /// want the canonical DIE for.  And the value of the element at
  /// that index is the canonical DIE offset we are looking for.
  ///
  /// @param canonical_die_offset out parameter.  This is set to the
  /// resulting canonical DIE that was computed.
  ///
  /// @param die_as_type if yes, it means @p die has to be considered
  /// as a type.
  void
  compute_canonical_die(Dwarf_Off die_offset,
            die_source source,
            offset_offset_map_type& canonical_dies,
            Dwarf_Die &canonical_die,
            bool die_as_type) const
  {
    // The map that associates the string representation of 'die'
    // with a vector of offsets of potentially equivalent DIEs.
    istring_dwarf_offsets_map_type& map =
      die_as_type
      ? (const_cast<reader*>(this)->
     type_die_repr_die_offsets_maps().get_container(source))
      : (const_cast<reader*>(this)->
     decl_die_repr_die_offsets_maps().get_container(source));
 
    Dwarf_Die die;
    ABG_ASSERT(dwarf_offdie(const_cast<Dwarf*>(dwarf_per_die_source(source)),
                die_offset, &die));
 
    // The variable repr is the the string representation of 'die'.
    //
    // Even if die_as_type is true -- which means that 'die' is said
    // to be considered as a type -- we always consider a
    // DW_TAG_subprogram DIE as a decl here, as far as its string
    // representation is concerned.
    interned_string name =
      (die_as_type)
      ? get_die_pretty_type_representation(&die, /*where=*/0)
      : get_die_pretty_representation(&die, /*where=*/0);
 
    Dwarf_Off canonical_die_offset = 0;
    istring_dwarf_offsets_map_type::iterator i = map.find(name);
    if (i == map.end())
      {
    dwarf_offsets_type offsets;
    offsets.push_back(die_offset);
    map[name] = offsets;
    set_canonical_die_offset(canonical_dies, die_offset, die_offset);
    get_die_from_offset(source, die_offset, &canonical_die);
    return;
      }
 
    Dwarf_Off cur_die_offset;
    Dwarf_Die potential_canonical_die;
    for (dwarf_offsets_type::const_iterator o = i->second.begin();
     o != i->second.end();
     ++o)
      {
    cur_die_offset = *o;
    get_die_from_offset(source, cur_die_offset, &potential_canonical_die);
    if (compare_dies(*this, &die, &potential_canonical_die,
             /*update_canonical_dies_on_the_fly=*/false))
      {
        canonical_die_offset = cur_die_offset;
        set_canonical_die_offset(canonical_dies, die_offset,
                     canonical_die_offset);
        get_die_from_offset(source, canonical_die_offset, &canonical_die);
        return;
      }
      }
 
    canonical_die_offset = die_offset;
    i->second.push_back(die_offset);
    set_canonical_die_offset(canonical_dies, die_offset, die_offset);
    get_die_from_offset(source, canonical_die_offset, &canonical_die);
  }
 
  /// Getter of the canonical DIE of a given DIE.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param canonical_die output parameter.  Is set to the resulting
  /// canonical die, if this function returns true.
  ///
  /// @param where the offset of the logical DIE we are supposed to be
  /// calling this function from.  If set to zero this means this is
  /// to be ignored.
  ///
  /// @param die_as_type if set to yes, it means @p die is to be
  /// considered as a type DIE.
  ///
  /// @return true iff a canonical DIE was found for @p die.
  bool
  get_canonical_die(const Dwarf_Die *die,
            Dwarf_Die &canonical_die,
            size_t where,
            bool die_as_type)
  {
    const die_source source = get_die_source(die);
 
    offset_offset_map_type &canonical_dies =
      die_as_type
      ? const_cast<reader*>(this)->canonical_type_die_offsets_.
      get_container(source)
      : const_cast<reader*>(this)->canonical_decl_die_offsets_.
      get_container(source);
 
    Dwarf_Off die_offset = dwarf_dieoffset(const_cast<Dwarf_Die*>(die));
    if (Dwarf_Off canonical_die_offset =
    get_canonical_die_offset(canonical_dies, die_offset))
      {
    get_die_from_offset(source, canonical_die_offset, &canonical_die);
    return true;
      }
 
    // The map that associates the string representation of 'die'
    // with a vector of offsets of potentially equivalent DIEs.
    istring_dwarf_offsets_map_type& map =
      die_as_type
      ? (const_cast<reader*>(this)->
     type_die_repr_die_offsets_maps().get_container(*this, die))
      : (const_cast<reader*>(this)->
     decl_die_repr_die_offsets_maps().get_container(*this, die));
 
    // The variable repr is the the string representation of 'die'.
    //
    // Even if die_as_type is true -- which means that 'die' is said
    // to be considered as a type -- we always consider a
    // DW_TAG_subprogram DIE as a decl here, as far as its string
    // representation is concerned.
    interned_string name =
      (die_as_type /*&& dwarf_tag(die) != DW_TAG_subprogram*/)
      ? get_die_pretty_type_representation(die, where)
      : get_die_pretty_representation(die, where);
 
    istring_dwarf_offsets_map_type::iterator i = map.find(name);
    if (i == map.end())
      return false;
 
    Dwarf_Off cur_die_offset;
    for (dwarf_offsets_type::const_iterator o = i->second.begin();
     o != i->second.end();
     ++o)
      {
    cur_die_offset = *o;
    get_die_from_offset(source, cur_die_offset, &canonical_die);
    // compare die and canonical_die.
    if (compare_dies_during_canonicalization(const_cast<reader&>(*this),
                         die, &canonical_die,
                         /*update_canonical_dies_on_the_fly=*/true))
      {
        set_canonical_die_offset(canonical_dies,
                     die_offset,
                     cur_die_offset);
        return true;
      }
      }
 
    return false;
  }
 
  /// Retrieve the canonical DIE of a given DIE.
  ///
  /// The canonical DIE is a DIE that is structurally equivalent to
  /// this one.
  ///
  /// Note that this function caches the canonical DIE that was
  /// computed.  Subsequent invocations of this function on the same
  /// DIE return the same cached DIE.
  ///
  /// @param die the DIE to get a canonical type for.
  ///
  /// @param canonical_die the resulting canonical DIE.
  ///
  /// @param where the offset of the logical DIE we are supposed to be
  /// calling this function from.  If set to zero this means this is
  /// to be ignored.
  ///
  /// @param die_as_type if true, consider DIE is a type.
  ///
  /// @return true if an *existing* canonical DIE was found.
  /// Otherwise, @p die is considered as being a canonical DIE for
  /// itself. @p canonical_die is thus set to the canonical die in
  /// either cases.
  bool
  get_or_compute_canonical_die(const Dwarf_Die* die,
                   Dwarf_Die& canonical_die,
                   size_t where,
                   bool die_as_type) const
  {
    const die_source source = get_die_source(die);
 
    offset_offset_map_type &canonical_dies =
      die_as_type
      ? const_cast<reader*>(this)->canonical_type_die_offsets_.
      get_container(source)
      : const_cast<reader*>(this)->canonical_decl_die_offsets_.
      get_container(source);
 
    Dwarf_Off initial_die_offset = dwarf_dieoffset(const_cast<Dwarf_Die*>(die));
 
    if (Dwarf_Off canonical_die_offset =
    get_canonical_die_offset(canonical_dies,
                 initial_die_offset))
      {
    get_die_from_offset(source, canonical_die_offset, &canonical_die);
    return true;
      }
 
    if (!is_type_die_to_be_canonicalized(die))
      return false;
 
    // The map that associates the string representation of 'die'
    // with a vector of offsets of potentially equivalent DIEs.
    istring_dwarf_offsets_map_type& map =
      die_as_type
      ? (const_cast<reader*>(this)->
     type_die_repr_die_offsets_maps().get_container(*this, die))
      : (const_cast<reader*>(this)->
     decl_die_repr_die_offsets_maps().get_container(*this, die));
 
    // The variable repr is the the string representation of 'die'.
    //
    // Even if die_as_type is true -- which means that 'die' is said
    // to be considered as a type -- we always consider a
    // DW_TAG_subprogram DIE as a decl here, as far as its string
    // representation is concerned.
    interned_string name =
      (die_as_type)
      ? get_die_pretty_type_representation(die, where)
      : get_die_pretty_representation(die, where);
 
    istring_dwarf_offsets_map_type::iterator i = map.find(name);
    if (i == map.end())
      {
    dwarf_offsets_type offsets;
    offsets.push_back(initial_die_offset);
    map[name] = offsets;
    get_die_from_offset(source, initial_die_offset, &canonical_die);
    set_canonical_die_offset(canonical_dies,
                 initial_die_offset,
                 initial_die_offset);
    return false;
      }
 
    // walk i->second without any iterator (using a while loop rather
    // than a for loop) because compare_dies might add new content to
    // the end of the i->second vector during the walking.
    dwarf_offsets_type::size_type n = 0, s = i->second.size();
    while (n < s)
      {
    Dwarf_Off die_offset = i->second[n];
    get_die_from_offset(source, die_offset, &canonical_die);
    // compare die and canonical_die.
    if (compare_dies_during_canonicalization(const_cast<reader&>(*this),
                         die, &canonical_die,
                         /*update_canonical_dies_on_the_fly=*/true))
      {
        set_canonical_die_offset(canonical_dies,
                     initial_die_offset,
                     die_offset);
        return true;
      }
    ++n;
      }
 
    // We didn't find a canonical DIE for 'die'.  So let's consider
    // that it is its own canonical DIE.
    get_die_from_offset(source, initial_die_offset, &canonical_die);
    i->second.push_back(initial_die_offset);
    set_canonical_die_offset(canonical_dies,
                 initial_die_offset,
                 initial_die_offset);
 
    return false;
  }
 
  /// Get the source of the DIE.
  ///
  /// The function returns an enumerator value saying if the DIE comes
  /// from the .debug_info section of the primary debug info file, the
  /// .debug_info section of the alternate debug info file, or the
  /// .debug_types section.
  ///
  /// @param die the DIE to get the source of.
  ///
  /// @return the source of the DIE if it could be determined,
  /// NO_DEBUG_INFO_DIE_SOURCE otherwise.
  die_source
  get_die_source(const Dwarf_Die *die) const
  {
    die_source source = NO_DEBUG_INFO_DIE_SOURCE;
    ABG_ASSERT(die);
    ABG_ASSERT(get_die_source(*die, source));
    return source;
  }
 
  /// Get the source of the DIE.
  ///
  /// The function returns an enumerator value saying if the DIE comes
  /// from the .debug_info section of the primary debug info file, the
  /// .debug_info section of the alternate debug info file, or the
  /// .debug_types section.
  ///
  /// @param die the DIE to get the source of.
  ///
  /// @param source out parameter.  The function sets this parameter
  /// to the source of the DIE @p iff it returns true.
  ///
  /// @return true iff the source of the DIE could be determined and
  /// returned.
  bool
  get_die_source(const Dwarf_Die &die, die_source &source) const
  {
    Dwarf_Die cu_die;
    Dwarf_Die cu_kind;
    uint8_t address_size = 0, offset_size = 0;
    if (!dwarf_diecu(const_cast<Dwarf_Die*>(&die),
             &cu_die, &address_size,
             &offset_size))
      return false;
 
    Dwarf_Half version = 0;
    Dwarf_Off abbrev_offset = 0;
    uint64_t type_signature = 0;
    Dwarf_Off type_offset = 0;
    if (!dwarf_cu_die(cu_die.cu, &cu_kind,
              &version, &abbrev_offset,
              &address_size, &offset_size,
              &type_signature, &type_offset))
      return false;
 
    int tag = dwarf_tag(&cu_kind);
 
    if (tag == DW_TAG_compile_unit
    || tag == DW_TAG_partial_unit)
      {
    const Dwarf *die_dwarf = dwarf_cu_getdwarf(cu_die.cu);
    if (dwarf_debug_info() == die_dwarf)
      source = PRIMARY_DEBUG_INFO_DIE_SOURCE;
    else if (alternate_dwarf_debug_info() == die_dwarf)
      source = ALT_DEBUG_INFO_DIE_SOURCE;
    else
      ABG_ASSERT_NOT_REACHED;
      }
    else if (tag == DW_TAG_type_unit)
      source = TYPE_UNIT_DIE_SOURCE;
    else
      return false;
 
    return true;
  }
 
  /// Getter for the DIE designated by an offset.
  ///
  /// @param source the source of the DIE to get.
  ///
  /// @param offset the offset of the DIE to get.
  ///
  /// @param die the resulting DIE.  The pointer has to point to an
  /// allocated memory region.
  void
  get_die_from_offset(die_source source, Dwarf_Off offset, Dwarf_Die *die) const
  {
    if (source == TYPE_UNIT_DIE_SOURCE)
      ABG_ASSERT(dwarf_offdie_types(const_cast<Dwarf*>(dwarf_per_die_source(source)),
                    offset, die));
    else
      ABG_ASSERT(dwarf_offdie(const_cast<Dwarf*>(dwarf_per_die_source(source)),
                  offset, die));
  }
 
public:
 
  /// Add an entry to the relevant die->decl map.
  ///
  /// @param die the DIE to add the the map.
  ///
  /// @param decl the decl to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @param do_associate_by_repr if true then this function
  /// associates the representation string of @p die with the
  /// declaration @p decl, in a corpus-wide manner.  That is, in the
  /// entire current corpus, there is going to be just one declaration
  /// associated with a DIE of the string representation of @p die.
  ///
  /// @param do_associate_by_repr_per_tu if true, then this function
  /// associates the representation string of @p die with the
  /// declaration @p decl in a translation unit wide manner.  That is,
  /// in the entire current translation unit, there is going to be
  /// just one declaration associated with a DIE of the string
  /// representation of @p die.
  void
  associate_die_to_decl(Dwarf_Die* die,
            decl_base_sptr decl,
            size_t where_offset,
            bool do_associate_by_repr = false)
  {
    const die_source source = get_die_source(die);
 
    die_artefact_map_type& m =
      decl_die_artefact_maps().get_container(source);
 
    size_t die_offset;
    if (do_associate_by_repr)
      {
    Dwarf_Die equiv_die;
    if (!get_or_compute_canonical_die(die, equiv_die, where_offset,
                      /*die_as_type=*/false))
      return;
    die_offset = dwarf_dieoffset(&equiv_die);
      }
    else
      die_offset = dwarf_dieoffset(die);
 
    m[die_offset] = decl;
  }
 
  /// Lookup the decl for a given DIE.
  ///
  /// The returned decl is either the decl of the DIE that as the
  /// exact offset @p die_offset
  /// die_offset, or
  /// give
  ///
  /// @param die_offset the offset of the DIE to consider.
  ///
  /// @param source where the DIE represented by @p die_offset comes
  /// from.
  ///
  /// Note that "alternate debug info sections" is a GNU extension as
  /// of DWARF4 and is described at
  /// http://www.dwarfstd.org/ShowIssue.php?issue=120604.1
  ///
  /// @return the resulting decl, or null if no decl is associated to
  /// the DIE represented by @p die_offset.
  decl_base_sptr
  lookup_decl_from_die_offset(Dwarf_Off die_offset, die_source source)
  {
    decl_base_sptr result =
      is_decl(lookup_artifact_from_die_offset(die_offset, source,
                          /*die_as_type=*/false));
 
    return result;
  }
 
  /// Get the qualified name of a given DIE.
  ///
  /// If the name of the DIE was already computed before just return
  /// that name from a cache.  Otherwise, build the name, cache it and
  /// return it.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @return the interned string representing the qualified name of
  /// @p die.
  interned_string
  get_die_qualified_name(Dwarf_Die *die, size_t where_offset)
  {
    ABG_ASSERT(die);
    die_istring_map_type& map =
      die_qualified_name_maps_.get_container(*this, die);
 
    size_t die_offset = dwarf_dieoffset(die);
    die_istring_map_type::const_iterator i = map.find(die_offset);
 
    if (i == map.end())
      {
    reader& rdr  = *const_cast<reader*>(this);
    string qualified_name = die_qualified_name(rdr, die, where_offset);
    interned_string istr = env().intern(qualified_name);
    map[die_offset] = istr;
    return istr;
      }
 
    return i->second;
  }
 
  /// Get the qualified name of a given DIE.
  ///
  /// If the name of the DIE was already computed before just return
  /// that name from a cache.  Otherwise, build the name, cache it and
  /// return it.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @return the interned string representing the qualified name of
  /// @p die.
  interned_string
  get_die_qualified_name(Dwarf_Die *die, size_t where_offset) const
  {
    return const_cast<reader*>(this)->
      get_die_qualified_name(die, where_offset);
  }
 
  /// Get the qualified name of a given DIE which is considered to be
  /// the DIE for a type.
  ///
  /// For instance, for a DW_TAG_subprogram DIE, this function
  /// computes the name of the function *type* that corresponds to the
  /// function.
  ///
  /// If the name of the DIE was already computed before just return
  /// that name from a cache.  Otherwise, build the name, cache it and
  /// return it.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @return the interned string representing the qualified name of
  /// @p die.
  interned_string
  get_die_qualified_type_name(const Dwarf_Die *die, size_t where_offset) const
  {
    ABG_ASSERT(die);
 
    // The name of the translation unit die is "".
    if (die == cur_tu_die())
      return env().intern("");
 
    die_istring_map_type& map =
      die_qualified_name_maps_.get_container(*const_cast<reader*>(this),
                         die);
 
    size_t die_offset = dwarf_dieoffset(const_cast<Dwarf_Die*>(die));
    die_istring_map_type::const_iterator i =
      map.find(die_offset);
 
    if (i == map.end())
      {
    reader& rdr  = *const_cast<reader*>(this);
    string qualified_name;
    int tag = dwarf_tag(const_cast<Dwarf_Die*>(die));
    if ((tag == DW_TAG_structure_type
         || tag == DW_TAG_class_type
         || tag == DW_TAG_union_type)
        && die_is_anonymous(die))
      {
        location l = die_location(*this, die);
        qualified_name = l ? l.expand() : "noloc";
        qualified_name = "unnamed-at-" + qualified_name;
      }
    else
      qualified_name =
        die_qualified_type_name(rdr, die, where_offset);
 
    interned_string istr = env().intern(qualified_name);
    map[die_offset] = istr;
    return istr;
      }
 
    return i->second;
  }
 
  /// Get the pretty representation of a DIE that represents a type.
  ///
  /// For instance, for the DW_TAG_subprogram, this function computes
  /// the pretty representation of the type of the function, not the
  /// pretty representation of the function declaration.
  ///
  /// Once the pretty representation is computed, it's stored in a
  /// cache.  Subsequent invocations of this function on the same DIE
  /// will yield the cached name.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @return the interned_string that represents the pretty
  /// representation.
  interned_string
  get_die_pretty_type_representation(const Dwarf_Die *die,
                     size_t where_offset) const
  {
    ABG_ASSERT(die);
    die_istring_map_type& map =
      die_pretty_type_repr_maps_.get_container(*const_cast<reader*>(this),
                           die);
 
    size_t die_offset = dwarf_dieoffset(const_cast<Dwarf_Die*>(die));
    die_istring_map_type::const_iterator i = map.find(die_offset);
 
    if (i == map.end())
      {
    reader& rdr = *const_cast<reader*>(this);
    string pretty_representation =
      die_pretty_print_type(rdr, die, where_offset);
    interned_string istr = env().intern(pretty_representation);
    map[die_offset] = istr;
    return istr;
      }
 
    return i->second;
  }
 
  /// Get the pretty representation of a DIE.
  ///
  /// Once the pretty representation is computed, it's stored in a
  /// cache.  Subsequent invocations of this function on the same DIE
  /// will yield the cached name.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @return the interned_string that represents the pretty
  /// representation.
  interned_string
  get_die_pretty_representation(const Dwarf_Die *die, size_t where_offset) const
  {
    ABG_ASSERT(die);
 
    die_istring_map_type& map =
      die_pretty_repr_maps_.get_container(*const_cast<reader*>(this),
                      die);
 
    size_t die_offset = dwarf_dieoffset(const_cast<Dwarf_Die*>(die));
    die_istring_map_type::const_iterator i = map.find(die_offset);
 
    if (i == map.end())
      {
    reader& rdr = *const_cast<reader*>(this);
    string pretty_representation =
      die_pretty_print(rdr, die, where_offset);
    interned_string istr = env().intern(pretty_representation);
    map[die_offset] = istr;
    return istr;
      }
 
    return i->second;
  }
 
  /// Lookup the artifact that was built to represent a type that has
  /// the same pretty representation as the type denoted by a given
  /// DIE.
  ///
  /// Note that the DIE must have previously been associated with the
  /// artifact using the functions associate_die_to_decl or
  /// associate_die_to_type.
  ///
  /// Also, note that the scope of the lookup is the current ABI
  /// corpus.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @return the type artifact found.
  type_or_decl_base_sptr
  lookup_type_artifact_from_die(Dwarf_Die *die) const
  {
    type_or_decl_base_sptr artifact =
      lookup_artifact_from_die(die, /*type_as_die=*/true);
    if (function_decl_sptr fn = is_function_decl(artifact))
      return fn->get_type();
    return artifact;
  }
 
  /// Lookup the artifact that was built to represent a type or a
  /// declaration that has the same pretty representation as the type
  /// denoted by a given DIE.
  ///
  /// Note that the DIE must have previously been associated with the
  /// artifact using the functions associate_die_to_decl or
  /// associate_die_to_type.
  ///
  /// Also, note that the scope of the lookup is the current ABI
  /// corpus.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @param die_as_type if true, it means the DIE is to be considered
  /// as a type.
  ///
  /// @return the artifact found.
  type_or_decl_base_sptr
  lookup_artifact_from_die(const Dwarf_Die *die, bool die_as_type = false) const
  {
    Dwarf_Die equiv_die;
    if (!get_or_compute_canonical_die(die, equiv_die, /*where=*/0, die_as_type))
      return type_or_decl_base_sptr();
 
    const die_artefact_map_type& m =
      die_as_type
      ? type_die_artefact_maps().get_container(*this, &equiv_die)
      : decl_die_artefact_maps().get_container(*this, &equiv_die);
 
    size_t die_offset = dwarf_dieoffset(&equiv_die);
    die_artefact_map_type::const_iterator i = m.find(die_offset);
 
    if (i == m.end())
      return type_or_decl_base_sptr();
    return i->second;
  }
 
  /// Lookup the artifact that was built to represent a type or a
  /// declaration that has the same pretty representation as the type
  /// denoted by the offset of a given DIE.
  ///
  /// Note that the DIE must have previously been associated with the
  /// artifact using either associate_die_to_decl or
  /// associate_die_to_type.
  ///
  /// Also, note that the scope of the lookup is the current ABI
  /// corpus.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  ///
  /// @param die_as_type if true, it means the DIE is to be considered
  /// as a type.
  ///
  /// @return the artifact found.
  type_or_decl_base_sptr
  lookup_artifact_from_die_offset(Dwarf_Off die_offset,
                  die_source source,
                  bool die_as_type = false) const
  {
    const die_artefact_map_type& m =
      die_as_type
      ? type_die_artefact_maps().get_container(source)
      : decl_die_artefact_maps().get_container(source);
 
    die_artefact_map_type::const_iterator i = m.find(die_offset);
    if (i == m.end())
      return type_or_decl_base_sptr();
    return i->second;
  }
 
  /// Get the language used to generate a given DIE.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param lang the resulting language.
  ///
  /// @return true iff the language of the DIE was found.
  bool
  get_die_language(const Dwarf_Die *die, translation_unit::language &lang) const
  {
    Dwarf_Die cu_die;
    ABG_ASSERT(dwarf_diecu(const_cast<Dwarf_Die*>(die), &cu_die, 0, 0));
 
    uint64_t l = 0;
    if (!die_unsigned_constant_attribute(&cu_die, DW_AT_language, l))
      return false;
 
    lang = dwarf_language_to_tu_language(l);
    return true;
  }
 
  /// Test if a given DIE originates from a program written in the C
  /// language.
  ///
  /// @param die the DIE to consider.
  ///
  /// @return true iff @p die originates from a program in the C
  /// language.
  bool
  die_is_in_c(const Dwarf_Die *die) const
  {
    translation_unit::language l = translation_unit::LANG_UNKNOWN;
    if (!get_die_language(die, l))
      return false;
    return is_c_language(l);
  }
 
  /// Test if a given DIE originates from a program written in the C++
  /// language.
  ///
  /// @param die the DIE to consider.
  ///
  /// @return true iff @p die originates from a program in the C++
  /// language.
  bool
  die_is_in_cplus_plus(const Dwarf_Die *die) const
  {
    translation_unit::language l = translation_unit::LANG_UNKNOWN;
    if (!get_die_language(die, l))
      return false;
    return is_cplus_plus_language(l);
  }
 
  /// Test if a given DIE originates from a program written either in
  /// C or C++.
  ///
  /// @param die the DIE to consider.
  ///
  /// @return true iff @p die originates from a program written either in
  /// C or C++.
  bool
  die_is_in_c_or_cplusplus(const Dwarf_Die *die) const
  {
    translation_unit::language l = translation_unit::LANG_UNKNOWN;
    if (!get_die_language(die, l))
      return false;
    return (is_cplus_plus_language(l) || is_c_language(l));
  }
 
  /// Check if we can assume the One Definition Rule[1] to be relevant
  /// for the current translation unit.
  ///
  /// [1]: https://en.wikipedia.org/wiki/One_Definition_Rule
  ///
  /// At the moment this returns true if the current translation unit
  /// is in C++ language.  In that case, it's relevant to assume that
  /// we use optimizations based on the ODR.
  bool
  odr_is_relevant() const
  {return odr_is_relevant(cur_transl_unit()->get_language());}
 
  /// Check if we can assume the One Definition Rule[1] to be relevant
  /// for a given language.
  ///
  /// [1]: https://en.wikipedia.org/wiki/One_Definition_Rule
  ///
  /// At the moment this returns true if the language considered
  /// is C++, Java or Ada.
  bool
  odr_is_relevant(translation_unit::language l) const
  {
    return (is_cplus_plus_language(l)
        || is_java_language(l)
        || is_ada_language(l));
  }
 
  /// Check if we can assume the One Definition Rule to be relevant
  /// for a given DIE.
  ///
  /// @param die the DIE to consider.
  ///
  /// @return true if the ODR is relevant for @p die.
  bool
  odr_is_relevant(Dwarf_Off die_offset, die_source source) const
  {
    Dwarf_Die die;
    ABG_ASSERT(dwarf_offdie(const_cast<Dwarf*>(dwarf_per_die_source(source)),
                die_offset, &die));
    return odr_is_relevant(&die);
  }
 
  /// Check if we can assume the One Definition Rule to be relevant
  /// for a given DIE.
  ///
  /// @param die the DIE to consider.
  ///
  /// @return true if the ODR is relevant for @p die.
  bool
  odr_is_relevant(const Dwarf_Die *die) const
  {
    translation_unit::language lang;
    if (!get_die_language(die, lang))
      return odr_is_relevant();
 
    return odr_is_relevant(lang);
  }
 
  /// Getter for the maps set that associates a decl DIE offset to an
  /// artifact.
  ///
  /// @return the maps set that associates a decl DIE offset to an
  /// artifact.
  die_source_dependant_container_set<die_artefact_map_type>&
  decl_die_artefact_maps()
  {return decl_die_artefact_maps_;}
 
  /// Getter for the maps set that associates a decl DIE offset to an
  /// artifact.
  ///
  /// @return the maps set that associates a decl DIE offset to an
  /// artifact.
  const die_source_dependant_container_set<die_artefact_map_type>&
  decl_die_artefact_maps() const
  {return decl_die_artefact_maps_;}
 
  /// Getter for the maps set that associates a type DIE offset to an
  /// artifact.
  ///
  /// @return the maps set that associates a type DIE offset to an
  /// artifact.
  die_source_dependant_container_set<die_artefact_map_type>&
  type_die_artefact_maps()
  {return type_die_artefact_maps_;}
 
  /// Getter for the maps set that associates a type DIE offset to an
  /// artifact.
  ///
  /// @return the maps set that associates a type DIE offset to an
  /// artifact.
  const die_source_dependant_container_set<die_artefact_map_type>&
  type_die_artefact_maps() const
  {return type_die_artefact_maps_;}
 
  /// Getter of the maps that associates function type representations
  /// to function types, inside a translation unit.
  ///
  /// @return the maps that associates function type representations
  /// to function types, inside a translation unit.
  istring_fn_type_map_type&
  per_tu_repr_to_fn_type_maps()
  {return per_tu_repr_to_fn_type_maps_;}
 
  /// Getter of the maps that associates function type representations
  /// to function types, inside a translation unit.
  ///
  /// @return the maps that associates function type representations
  /// to function types, inside a translation unit.
  const istring_fn_type_map_type&
  per_tu_repr_to_fn_type_maps() const
  {return per_tu_repr_to_fn_type_maps_;}
 
  /// Associate the representation of a function type DIE to a given
  /// function type, inside the current translation unit.
  ///
  /// @param die the DIE to associate to the function type, using its
  /// representation.
  ///
  /// @param fn_type the function type to associate to @p die.
  void
  associate_die_repr_to_fn_type_per_tu(const Dwarf_Die *die,
                       const function_type_sptr &fn_type)
  {
    if (!die_is_function_type(die))
      return;
 
    interned_string repr =
      get_die_pretty_type_representation(die, /*where=*/0);
    ABG_ASSERT(!repr.empty());
 
    per_tu_repr_to_fn_type_maps()[repr]= fn_type;
  }
 
  /// Lookup the function type associated to a given function type
  /// DIE, in the current translation unit.
  ///
  /// @param die the DIE of function type to consider.
  ///
  /// @return the @ref function_type_sptr associated to @p die, or nil
  /// of no function_type is associated to @p die.
  function_type_sptr
  lookup_fn_type_from_die_repr_per_tu(const Dwarf_Die *die)
  {
    if (!die_is_function_type(die))
      return function_type_sptr();
 
    interned_string repr = die_name(die).empty() ?
      get_die_pretty_type_representation(die, /*where=*/0)
      : get_die_pretty_representation(die, /*where=*/0);
    ABG_ASSERT(!repr.empty());
 
    istring_fn_type_map_type::const_iterator i =
      per_tu_repr_to_fn_type_maps().find(repr);
 
    if (i == per_tu_repr_to_fn_type_maps().end())
      return function_type_sptr();
 
    return i->second;
  }
 
  /// Set the canonical DIE offset of a given DIE.
  ///
  /// @param canonical_dies the vector that holds canonical DIEs.
  ///
  /// @param die_offset the offset of the DIE to set the canonical DIE
  /// for.
  ///
  /// @param canonical_die_offset the canonical DIE offset to
  /// associate to @p die_offset.
  void
  set_canonical_die_offset(offset_offset_map_type &canonical_dies,
               Dwarf_Off die_offset,
               Dwarf_Off canonical_die_offset) const
  {
    canonical_dies[die_offset] = canonical_die_offset;}
 
  /// Set the canonical DIE offset of a given DIE.
  ///
  ///
  /// @param die_offset the offset of the DIE to set the canonical DIE
  /// for.
  ///
  /// @param source the source of the DIE denoted by @p die_offset.
  ///
  /// @param canonical_die_offset the canonical DIE offset to
  /// associate to @p die_offset.
  ///
  /// @param die_as_type if true, it means that @p die_offset has to
  /// be considered as a type.
  void
  set_canonical_die_offset(Dwarf_Off die_offset,
               die_source source,
               Dwarf_Off canonical_die_offset,
               bool die_as_type) const
  {
    offset_offset_map_type &canonical_dies =
      die_as_type
      ? const_cast<reader*>(this)->canonical_type_die_offsets_.
      get_container(source)
      : const_cast<reader*>(this)->canonical_decl_die_offsets_.
      get_container(source);
 
    set_canonical_die_offset(canonical_dies,
                 die_offset,
                 canonical_die_offset);
  }
 
  /// Set the canonical DIE offset of a given DIE.
  ///
  ///
  /// @param die the DIE to set the canonical DIE for.
  ///
  /// @param canonical_die_offset the canonical DIE offset to
  /// associate to @p die_offset.
  ///
  /// @param die_as_type if true, it means that @p die has to be
  /// considered as a type.
  void
  set_canonical_die_offset(const Dwarf_Die *die,
               Dwarf_Off canonical_die_offset,
               bool die_as_type) const
  {
    const die_source source = get_die_source(die);
 
    Dwarf_Off die_offset = dwarf_dieoffset(const_cast<Dwarf_Die*>(die));
 
    set_canonical_die_offset(die_offset, source,
                 canonical_die_offset,
                 die_as_type);
  }
 
  /// Get the canonical DIE offset of a given DIE.
  ///
  /// @param canonical_dies the vector that contains canonical DIES.
  ///
  /// @param die_offset the offset of the DIE to consider.
  ///
  /// @return the canonical of the DIE denoted by @p die_offset, or
  /// zero if no canonical DIE was found.
  Dwarf_Off
  get_canonical_die_offset(offset_offset_map_type &canonical_dies,
               Dwarf_Off die_offset) const
  {
    offset_offset_map_type::const_iterator it = canonical_dies.find(die_offset);
    if (it == canonical_dies.end())
      return 0;
    return it->second;
  }
 
  /// Get the canonical DIE offset of a given DIE.
  ///
  /// @param die_offset the offset of the DIE to consider.
  ///
  /// @param source the source of the DIE denoted by @p die_offset.
  ///
  /// @param die_as_type if true, it means that @p is to be considered
  /// as a type DIE.
  ///
  /// @return the canonical of the DIE denoted by @p die_offset, or
  /// zero if no canonical DIE was found.
  Dwarf_Off
  get_canonical_die_offset(Dwarf_Off die_offset,
               die_source source,
               bool die_as_type) const
  {
    offset_offset_map_type &canonical_dies =
      die_as_type
      ? const_cast<reader*>(this)->canonical_type_die_offsets_.
      get_container(source)
      : const_cast<reader*>(this)->canonical_decl_die_offsets_.
      get_container(source);
 
    return get_canonical_die_offset(canonical_dies, die_offset);
  }
 
  /// Erase the canonical type of a given DIE.
  ///
  /// @param die_offset the offset of the DIE to consider.
  ///
  /// @param source the source of the canonical type.
  ///
  /// @param die_as_type if true, it means that @p is to be considered
  /// as a type DIE.
  ///
  /// @return the canonical of the DIE denoted by @p die_offset, or
  /// zero if no canonical DIE was found and erased..
  bool
  erase_canonical_die_offset(Dwarf_Off die_offset,
                 die_source source,
                 bool die_as_type) const
  {
    offset_offset_map_type &canonical_dies =
      die_as_type
      ? const_cast<reader*>(this)->canonical_type_die_offsets_.
      get_container(source)
      : const_cast<reader*>(this)->canonical_decl_die_offsets_.
      get_container(source);
 
    return canonical_dies.erase(die_offset);
  }
 
 
  /// Associate a DIE (representing a type) to the type that it
  /// represents.
  ///
  /// @param die the DIE to consider.
  ///
  /// @param type the type to associate the DIE to.
  ///
  /// @param where_offset where in the DIE stream we logically are.
  void
  associate_die_to_type(const Dwarf_Die *die,
            type_base_sptr  type,
            size_t      where)
  {
    if (!type)
      return;
 
    Dwarf_Die equiv_die;
    if (!get_or_compute_canonical_die(die, equiv_die, where,
                      /*die_as_type=*/true))
      return;
 
    die_artefact_map_type& m =
      type_die_artefact_maps().get_container(*this, &equiv_die);
 
    size_t die_offset = dwarf_dieoffset(&equiv_die);
    m[die_offset] = type;
  }
 
  /// Lookup the type associated to a given DIE.
  ///
  /// Note that the DIE must have been associated to type by a
  /// previous invocation of the function
  /// reader::associate_die_to_type().
  ///
  /// @param die the DIE to consider.
  ///
  /// @return the type associated to the DIE or NULL if no type is
  /// associated to the DIE.
  type_base_sptr
  lookup_type_from_die(const Dwarf_Die* die) const
  {
    type_or_decl_base_sptr artifact =
      lookup_artifact_from_die(die, /*die_as_type=*/true);
    if (function_decl_sptr fn = is_function_decl(artifact))
      return fn->get_type();
    return is_type(artifact);
  }
 
  /// Lookup the type associated to a DIE at a given offset, from a
  /// given source.
  ///
  /// Note that the DIE must have been associated to type by a
  /// previous invocation of the function
  /// reader::associate_die_to_type().
  ///
  /// @param die_offset the offset of the DIE to consider.
  ///
  /// @param source the source of the DIE to consider.
  ///
  /// @return the type associated to the DIE or NULL if no type is
  /// associated to the DIE.
  type_base_sptr
  lookup_type_from_die_offset(size_t die_offset, die_source source) const
  {
    type_base_sptr result;
    const die_artefact_map_type& m =
      type_die_artefact_maps().get_container(source);
    die_artefact_map_type::const_iterator i = m.find(die_offset);
    if (i != m.end())
      {
    if (function_decl_sptr fn = is_function_decl(i->second))
      return fn->get_type();
    result = is_type(i->second);
      }
 
    if (!result)
      {
    // Maybe we are looking for a class type being constructed?
    const die_class_or_union_map_type& m = die_wip_classes_map(source);
    die_class_or_union_map_type::const_iterator i = m.find(die_offset);
 
    if (i != m.end())
      result = i->second;
      }
 
    if (!result)
      {
    // Maybe we are looking for a function type being constructed?
    const die_function_type_map_type& m =
      die_wip_function_types_map(source);
    die_function_type_map_type::const_iterator i = m.find(die_offset);
 
    if (i != m.end())
      result = i->second;
      }
 
    return result;
  }
 
  /// Getter of a map that associates a die that represents a
  /// class/struct with the declaration of the class, while the class
  /// is being constructed.
  ///
  /// @param source where the DIE is from.
  ///
  /// @return the map that associates a DIE to the class that is being
  /// built.
  const die_class_or_union_map_type&
  die_wip_classes_map(die_source source) const
  {return const_cast<reader*>(this)->die_wip_classes_map(source);}
 
  /// Getter of a map that associates a die that represents a
  /// class/struct with the declaration of the class, while the class
  /// is being constructed.
  ///
  /// @param source where the DIE comes from.
  ///
  /// @return the map that associates a DIE to the class that is being
  /// built.
  die_class_or_union_map_type&
  die_wip_classes_map(die_source source)
  {
    switch (source)
      {
      case PRIMARY_DEBUG_INFO_DIE_SOURCE:
    break;
      case ALT_DEBUG_INFO_DIE_SOURCE:
    return alternate_die_wip_classes_map_;
      case TYPE_UNIT_DIE_SOURCE:
    return type_unit_die_wip_classes_map_;
      case NO_DEBUG_INFO_DIE_SOURCE:
      case NUMBER_OF_DIE_SOURCES:
    ABG_ASSERT_NOT_REACHED;
      }
    return die_wip_classes_map_;
  }
 
  /// Getter for a map that associates a die (that represents a
  /// function type) whith a function type, while the function type is
  /// being constructed (WIP == work in progress).
  ///
  /// @param source where the DIE comes from.n
  ///
  /// @return the map of wip function types.
  const die_function_type_map_type&
  die_wip_function_types_map(die_source source) const
  {return const_cast<reader*>(this)->die_wip_function_types_map(source);}
 
  /// Getter for a map that associates a die (that represents a
  /// function type) whith a function type, while the function type is
  /// being constructed (WIP == work in progress).
  ///
  /// @param source where DIEs of the map come from.
  ///
  /// @return the map of wip function types.
  die_function_type_map_type&
  die_wip_function_types_map(die_source source)
  {
    switch (source)
      {
      case PRIMARY_DEBUG_INFO_DIE_SOURCE:
    break;
      case ALT_DEBUG_INFO_DIE_SOURCE:
    return alternate_die_wip_function_types_map_;
      case TYPE_UNIT_DIE_SOURCE:
    return type_unit_die_wip_function_types_map_;
      case NO_DEBUG_INFO_DIE_SOURCE:
      case NUMBER_OF_DIE_SOURCES:
    ABG_ASSERT_NOT_REACHED;
      }
    return die_wip_function_types_map_;
  }
 
  /// Getter for a map that associates a die with a function decl
  /// which has a linkage name but no elf symbol yet.
  ///
  /// This is to fixup function decls with linkage names, but with no
  /// link to their underlying elf symbol.  There are some DIEs like
  /// that in DWARF sometimes, especially when the compiler optimizes
  /// stuff aggressively.
  die_function_decl_map_type&
  die_function_decl_with_no_symbol_map()
  {return die_function_with_no_symbol_map_;}
 
  /// Return true iff a given offset is for the DIE of a class that is
  /// being built, but that is not fully built yet.  WIP == "work in
  /// progress".
  ///
  /// @param offset the DIE offset to consider.
  ///
  /// @param source where the DIE of the map come from.
  ///
  /// @return true iff @p offset is the offset of the DIE of a class
  /// that is being currently built.
  bool
  is_wip_class_die_offset(Dwarf_Off offset, die_source source) const
  {
    die_class_or_union_map_type::const_iterator i =
      die_wip_classes_map(source).find(offset);
    return (i != die_wip_classes_map(source).end());
  }
 
  /// Return true iff a given offset is for the DIE of a function type
  /// that is being built at the moment, but is not fully built yet.
  /// WIP == work in progress.
  ///
  /// @param offset DIE offset to consider.
  ///
  /// @param source where the DIE comes from.
  ///
  /// @return true iff @p offset is the offset of the DIE of a
  /// function type that is being currently built.
  bool
  is_wip_function_type_die_offset(Dwarf_Off offset, die_source source) const
  {
    die_function_type_map_type::const_iterator i =
      die_wip_function_types_map(source).find(offset);
    return (i != die_wip_function_types_map(source).end());
  }
 
  /// Sometimes, a data member die can erroneously have an empty name as
  /// a result of a bug of the DWARF emitter.
  ///
  /// This is what happens in
  /// https://sourceware.org/bugzilla/show_bug.cgi?id=29934.
  ///
  /// In that case, this function constructs an artificial name for that
  /// data member.  The pattern of the name is as follows:
  ///
  ///          "unnamed-@-<location>".
  ///
  ///location is either the value of the data member location of the
  ///data member if it has one or  concatenation of its source location
  ///if it has none.  If no location can be calculated then the function
  ///returns the empty string.
  string
  build_name_for_buggy_anonymous_data_member(Dwarf_Die *die)
  {
    string result;
    // Let's make sure we are looking at a data member with an empty
    // name ...
    if (!die
    || dwarf_tag(die) != DW_TAG_member
    || !die_name(die).empty())
      return result;
 
    // ... and yet, it's not an anonymous data member (aka unnamed
    // field) as described in
    // https://gcc.gnu.org/onlinedocs/gcc/Unnamed-Fields.html.
    if (die_is_anonymous_data_member(die))
      return result;
 
    // If we come this far, it means we are looking at a buggy data
    // member with no name.  Let's build a name for it so that it can be
    // addressed.
    int64_t offset_in_bits = 0;
    bool has_offset = die_member_offset(*this, die, offset_in_bits);
    location loc;
    if (!has_offset)
      {
    loc = die_location(*this, die);
    if (!loc)
      return result;
      }
 
    std::ostringstream o;
    o << "unnamed-dm-@-";
    if (has_offset)
      o << "offset-" << offset_in_bits << "bits";
    else
      o << "loc-" << loc.expand();
 
    return o.str();
  }
 
  /// Getter for the map of declaration-only classes that are to be
  /// resolved to their definition classes by the end of the corpus
  /// loading.
  ///
  /// @return a map of string -> vector of classes where the key is
  /// the fully qualified name of the class and the value is the
  /// vector of declaration-only class.
  const string_classes_or_unions_map&
  declaration_only_classes() const
  {return decl_only_classes_map_;}
 
  /// Getter for the map of declaration-only classes that are to be
  /// resolved to their definition classes by the end of the corpus
  /// loading.
  ///
  /// @return a map of string -> vector of classes where the key is
  /// the fully qualified name of the class and the value is the
  /// vector of declaration-only class.
  string_classes_or_unions_map&
  declaration_only_classes()
  {return decl_only_classes_map_;}
 
  /// If a given class is a declaration-only class then stash it on
  /// the side so that at the end of the corpus reading we can resolve
  /// it to its definition.
  ///
  /// @param klass the class to consider.
  void
  maybe_schedule_declaration_only_class_for_resolution(const class_or_union_sptr& cou)
  {
    if (cou->get_is_declaration_only()
    && cou->get_definition_of_declaration() == 0)
      {
    string qn = cou->get_qualified_name();
    string_classes_or_unions_map::iterator record =
      declaration_only_classes().find(qn);
    if (record == declaration_only_classes().end())
      declaration_only_classes()[qn].push_back(cou);
    else
      record->second.push_back(cou);
      }
  }
 
  /// Test if a given declaration-only class has been scheduled for
  /// resolution to a defined class.
  ///
  /// @param klass the class to consider for the test.
  ///
  /// @return true iff @p klass is a declaration-only class and if
  /// it's been scheduled for resolution to a defined class.
  bool
  is_decl_only_class_scheduled_for_resolution(const class_or_union_sptr& cou)
  {
    if (cou->get_is_declaration_only())
      return (declaration_only_classes().find(cou->get_qualified_name())
          != declaration_only_classes().end());
 
    return false;
  }
 
  /// Compare two ABI artifacts in a context which canonicalization
  /// has not be done yet.
  ///
  /// @param l the left-hand-side operand of the comparison
  ///
  /// @param r the right-hand-side operand of the comparison.
  ///
  /// @return true if @p l equals @p r.
  bool
  compare_before_canonicalisation(const type_or_decl_base_sptr &l,
                  const type_or_decl_base_sptr &r)
  {
    if (!l || !r)
      return !!l == !!r;
 
    const environment& e = l->get_environment();
    ABG_ASSERT(!e.canonicalization_is_done());
 
    e.priv_->allow_type_comparison_results_caching(true);
    bool s0 = e.decl_only_class_equals_definition();
    e.decl_only_class_equals_definition(true);
    bool equal = l == r;
    e.decl_only_class_equals_definition(s0);
    e.priv_->clear_type_comparison_results_cache();
    e.priv_->allow_type_comparison_results_caching(false);
    return equal;
  }
 
  /// Walk the declaration-only classes that have been found during
  /// the building of the corpus and resolve them to their definitions.
  void
  resolve_declaration_only_classes()
  {
    vector<string> resolved_classes;
 
    for (string_classes_or_unions_map::iterator i =
       declaration_only_classes().begin();
     i != declaration_only_classes().end();
     ++i)
      {
    bool to_resolve = false;
    for (classes_or_unions_type::iterator j = i->second.begin();
         j != i->second.end();
         ++j)
      if ((*j)->get_is_declaration_only()
          && ((*j)->get_definition_of_declaration() == 0))
        to_resolve = true;
 
    if (!to_resolve)
      {
        resolved_classes.push_back(i->first);
        continue;
      }
 
    // Now, for each decl-only class that have the current name
    // 'i->first', let's try to poke at the fully defined class
    // that is defined in the same translation unit as the
    // declaration.
    //
    // If we find one class (defined in the TU of the declaration)
    // that defines the declaration, then the declaration can be
    // resolved to that class.
    //
    // If no defining class is found in the TU of the declaration,
    // then there are possibly three cases to consider:
    //
    //   1/ There is exactly one class that defines the
    //   declaration and that class is defined in another TU.  In
    //   this case, the declaration is resolved to that
    //   definition.
    //
    //   2/ There are more than one class that define that
    //   declaration and none of them is defined in the TU of the
    //   declaration.  If those classes are all different, then
    //   the declaration is left unresolved.
    //
    //   3/ No class defines the declaration.  In this case, the
    //   declaration is left unresoved.
 
    // So get the classes that might define the current
    // declarations which name is i->first.
    const type_base_wptrs_type *classes =
      lookup_class_types(i->first, *corpus());
    if (!classes)
      classes = lookup_union_types(i->first, *corpus());
 
    if (!classes)
      continue;
 
    // This is a map that associates the translation unit path to
    // the class (that potentially defines the declarations that
    // we consider) that are defined in that translation unit.  It
    // should stay ordered by using the TU path as key to ensure
    // stability of the order of classe definitions in ABIXML
    // output.
    map<string, class_or_union_sptr> per_tu_class_map;
    for (type_base_wptrs_type::const_iterator c = classes->begin();
         c != classes->end();
         ++c)
      {
        class_or_union_sptr klass = is_class_or_union_type(type_base_sptr(*c));
        ABG_ASSERT(klass);
 
        klass = is_class_or_union_type(look_through_decl_only_class(klass));
        if (klass->get_is_declaration_only())
          continue;
 
        string tu_path = klass->get_translation_unit()->get_absolute_path();
        if (tu_path.empty())
          continue;
 
        // Build a map that associates the translation unit path
        // to the class (that potentially defines the declarations
        // that we consider) that are defined in that translation unit.
        per_tu_class_map[tu_path] = klass;
      }
 
    if (!per_tu_class_map.empty())
      {
        // Walk the declarations to resolve and resolve them
        // either to the definitions that are in the same TU as
        // the declaration, or to the definition found elsewhere,
        // if there is only one such definition.
        for (classes_or_unions_type::iterator j = i->second.begin();
         j != i->second.end();
         ++j)
          {
        if ((*j)->get_is_declaration_only()
            && ((*j)->get_definition_of_declaration() == 0))
          {
            string tu_path =
              (*j)->get_translation_unit()->get_absolute_path();
            map<string, class_or_union_sptr>::const_iterator e =
              per_tu_class_map.find(tu_path);
            if (e != per_tu_class_map.end())
              (*j)->set_definition_of_declaration(e->second);
            else if (per_tu_class_map.size() == 1)
              (*j)->set_definition_of_declaration
            (per_tu_class_map.begin()->second);
            else
              {
            // We are in case where there are more than
            // one definition for the declaration.  Let's
            // see if they are all equal.  If they are,
            // then the declaration resolves to the
            // definition.  Otherwise, we are in the case
            // 3/ described above.
            map<string,
                class_or_union_sptr>::const_iterator it;
            class_or_union_sptr first_class =
              per_tu_class_map.begin()->second;
            bool all_class_definitions_are_equal = true;
            for (it = per_tu_class_map.begin();
                 it != per_tu_class_map.end();
                 ++it)
              {
                if (it == per_tu_class_map.begin())
                  continue;
                else
                  {
                if (!compare_before_canonicalisation(it->second,
                                     first_class))
                  {
                    all_class_definitions_are_equal = false;
                    break;
                  }
                  }
              }
            if (all_class_definitions_are_equal)
              (*j)->set_definition_of_declaration(first_class);
              }
          }
          }
        resolved_classes.push_back(i->first);
      }
      }
 
    size_t num_decl_only_classes = declaration_only_classes().size(),
      num_resolved = resolved_classes.size();
    if (show_stats())
      cerr << "resolved " << num_resolved
       << " class declarations out of "
       << num_decl_only_classes
       << "\n";
 
    for (vector<string>::const_iterator i = resolved_classes.begin();
     i != resolved_classes.end();
     ++i)
      declaration_only_classes().erase(*i);
 
    if (show_stats() && !declaration_only_classes().empty())
      {
    cerr << "Here are the "
         << num_decl_only_classes - num_resolved
         << " unresolved class declarations:\n";
    for (string_classes_or_unions_map::iterator i =
           declaration_only_classes().begin();
         i != declaration_only_classes().end();
         ++i)
      cerr << "    " << i->first << "\n";
      }
  }
 
  /// Getter for the map of declaration-only enums that are to be
  /// resolved to their definition enums by the end of the corpus
  /// loading.
  ///
  /// @return a map of string -> vector of enums where the key is
  /// the fully qualified name of the enum and the value is the
  /// vector of declaration-only enum.
  const string_enums_map&
  declaration_only_enums() const
  {return decl_only_enums_map_;}
 
  /// Getter for the map of declaration-only enums that are to be
  /// resolved to their definition enums by the end of the corpus
  /// loading.
  ///
  /// @return a map of string -> vector of enums where the key is
  /// the fully qualified name of the enum and the value is the
  /// vector of declaration-only enum.
  string_enums_map&
  declaration_only_enums()
  {return decl_only_enums_map_;}
 
  /// If a given enum is a declaration-only enum then stash it on
  /// the side so that at the end of the corpus reading we can resolve
  /// it to its definition.
  ///
  /// @param enom the enum to consider.
  void
  maybe_schedule_declaration_only_enum_for_resolution(enum_type_decl_sptr& enom)
  {
    if (enom->get_is_declaration_only()
    && enom->get_definition_of_declaration() == 0)
      {
    string qn = enom->get_qualified_name();
    string_enums_map::iterator record =
      declaration_only_enums().find(qn);
    if (record == declaration_only_enums().end())
      declaration_only_enums()[qn].push_back(enom);
    else
      record->second.push_back(enom);
      }
  }
 
  /// Test if a given declaration-only enum has been scheduled for
  /// resolution to a defined enum.
  ///
  /// @param enom the enum to consider for the test.
  ///
  /// @return true iff @p enom is a declaration-only enum and if
  /// it's been scheduled for resolution to a defined enum.
  bool
  is_decl_only_enum_scheduled_for_resolution(enum_type_decl_sptr& enom)
  {
    if (enom->get_is_declaration_only())
      return (declaration_only_enums().find(enom->get_qualified_name())
          != declaration_only_enums().end());
 
    return false;
  }
 
  /// Walk the declaration-only enums that have been found during
  /// the building of the corpus and resolve them to their definitions.
  ///
  /// TODO: Do away with this function by factorizing it with
  /// resolve_declaration_only_classes.  All declaration-only decls
  /// could be handled the same way as declaration-only-ness is a
  /// property of abigail::ir::decl_base now.
  void
  resolve_declaration_only_enums()
  {
    vector<string> resolved_enums;
 
    for (string_enums_map::iterator i =
       declaration_only_enums().begin();
     i != declaration_only_enums().end();
     ++i)
      {
    bool to_resolve = false;
    for (enums_type::iterator j = i->second.begin();
         j != i->second.end();
         ++j)
      if ((*j)->get_is_declaration_only()
          && ((*j)->get_definition_of_declaration() == 0))
        to_resolve = true;
 
    if (!to_resolve)
      {
        resolved_enums.push_back(i->first);
        continue;
      }
 
    // Now, for each decl-only enum that have the current name
    // 'i->first', let's try to poke at the fully defined enum
    // that is defined in the same translation unit as the
    // declaration.
    //
    // If we find one enum (defined in the TU of the declaration)
    // that defines the declaration, then the declaration can be
    // resolved to that enum.
    //
    // If no defining enum is found in the TU of the declaration,
    // then there are possibly three cases to consider:
    //
    //   1/ There is exactly one enum that defines the
    //   declaration and that enum is defined in another TU.  In
    //   this case, the declaration is resolved to that
    //   definition.
    //
    //   2/ There are more than one enum that define that
    //   declaration and none of them is defined in the TU of the
    //   declaration.  In this case, the declaration is left
    //   unresolved.
    //
    //   3/ No enum defines the declaration.  In this case, the
    //   declaration is left unresoved.
 
    // So get the enums that might define the current
    // declarations which name is i->first.
    const type_base_wptrs_type *enums =
      lookup_enum_types(i->first, *corpus());
    if (!enums)
      continue;
 
    // This is a map that associates the translation unit path to
    // the enum (that potentially defines the declarations that
    // we consider) that are defined in that translation unit.  It
    // should stay ordered by using the TU path as key to ensure
    // stability of the order of enum definitions in ABIXML
    // output.
    map<string, enum_type_decl_sptr> per_tu_enum_map;
    for (type_base_wptrs_type::const_iterator c = enums->begin();
         c != enums->end();
         ++c)
      {
        enum_type_decl_sptr enom = is_enum_type(type_base_sptr(*c));
        ABG_ASSERT(enom);
 
        enom = is_enum_type(look_through_decl_only_enum(enom));
        if (enom->get_is_declaration_only())
          continue;
 
        string tu_path = enom->get_translation_unit()->get_absolute_path();
        if (tu_path.empty())
          continue;
 
        // Build a map that associates the translation unit path
        // to the enum (that potentially defines the declarations
        // that we consider) that are defined in that translation unit.
        per_tu_enum_map[tu_path] = enom;
      }
 
    if (!per_tu_enum_map.empty())
      {
        // Walk the declarations to resolve and resolve them
        // either to the definitions that are in the same TU as
        // the declaration, or to the definition found elsewhere,
        // if there is only one such definition.
        for (enums_type::iterator j = i->second.begin();
         j != i->second.end();
         ++j)
          {
        if ((*j)->get_is_declaration_only()
            && ((*j)->get_definition_of_declaration() == 0))
          {
            string tu_path =
              (*j)->get_translation_unit()->get_absolute_path();
            map<string, enum_type_decl_sptr>::const_iterator e =
              per_tu_enum_map.find(tu_path);
            if (e != per_tu_enum_map.end())
              (*j)->set_definition_of_declaration(e->second);
            else if (per_tu_enum_map.size() == 1)
              (*j)->set_definition_of_declaration
            (per_tu_enum_map.begin()->second);
            else
              {
            // We are in case where there are more than
            // one definition for the declaration.  Let's
            // see if they are all equal.  If they are,
            // then the declaration resolves to the
            // definition.  Otherwise, we are in the case
            // 3/ described above.
            map<string,
                enum_type_decl_sptr>::const_iterator it;
            enum_type_decl_sptr first_enum =
              per_tu_enum_map.begin()->second;
            bool all_enum_definitions_are_equal = true;
            for (it = per_tu_enum_map.begin();
                 it != per_tu_enum_map.end();
                 ++it)
              {
                if (it == per_tu_enum_map.begin())
                  continue;
                else
                  {
                if (!compare_before_canonicalisation(it->second,
                                     first_enum))
                  {
                    all_enum_definitions_are_equal = false;
                    break;
                  }
                  }
              }
            if (all_enum_definitions_are_equal)
              (*j)->set_definition_of_declaration(first_enum);
              }
          }
          }
        resolved_enums.push_back(i->first);
      }
      }
 
    size_t num_decl_only_enums = declaration_only_enums().size(),
      num_resolved = resolved_enums.size();
    if (show_stats())
      cerr << "resolved " << num_resolved
       << " enum declarations out of "
       << num_decl_only_enums
       << "\n";
 
    for (vector<string>::const_iterator i = resolved_enums.begin();
     i != resolved_enums.end();
     ++i)
      declaration_only_enums().erase(*i);
 
    if (show_stats() && !declaration_only_enums().empty())
      {
    cerr << "Here are the "
         << num_decl_only_enums - num_resolved
         << " unresolved enum declarations:\n";
    for (string_enums_map::iterator i = declaration_only_enums().begin();
         i != declaration_only_enums().end();
         ++i)
      cerr << "    " << i->first << "\n";
      }
  }
 
  /// Test if a symbol belongs to a function of the current ABI
  /// corpus.
  ///
  /// This is a sub-routine of fixup_functions_with_no_symbols.
  ///
  /// @param fn the function symbol to consider.
  ///
  /// @returnt true if @p fn belongs to a function of the current ABI
  /// corpus.
  bool
  symbol_already_belongs_to_a_function(elf_symbol_sptr& fn)
  {
    corpus_sptr corp = corpus();
    if (!corp)
      return false;
 
    string id = fn->get_id_string();
 
    const std::unordered_set<function_decl*> *fns = corp->lookup_functions(id);
    if (!fns)
      return false;
 
    for (auto f : *fns)
      if (f->get_symbol())
    return true;
 
    return false;
  }
 
  /// Some functions described by DWARF may have their linkage name
  /// set, but no link to their actual underlying elf symbol.  When
  /// these are virtual member functions, comparing the enclosing type
  /// against another one which has its underlying symbol properly set
  /// might lead to spurious type changes.
  ///
  /// If the corpus contains a symbol with the same name as the
  /// linkage name of the function, then set up the link between the
  /// function and its underlying symbol.
  ///
  /// Note that for the moment, only virtual member functions are
  /// fixed up like this.  This is because they really are the only
  /// fuctions of functions that can affect types (in spurious ways).
  void
  fixup_functions_with_no_symbols()
  {
    corpus_sptr corp = corpus();
    if (!corp)
      return;
 
    die_function_decl_map_type &fns_with_no_symbol =
      die_function_decl_with_no_symbol_map();
 
    if (do_log())
      cerr << fns_with_no_symbol.size()
       << " functions to fixup, potentially\n";
 
    for (die_function_decl_map_type::iterator i = fns_with_no_symbol.begin();
     i != fns_with_no_symbol.end();
     ++i)
      if (elf_symbol_sptr sym =
      corp->lookup_function_symbol(i->second->get_linkage_name()))
    {
      // So i->second is a virtual member function that was
      // previously scheduled to be set a function symbol.
      //
      // But if it appears that it now has a symbol already set,
      // then do not set a symbol to it again.
      //
      // Or if it appears that another virtual member function
      // from the current ABI Corpus, with the same linkage
      // (mangled) name has already been set a symbol, then do not
      // set a symbol to this function either.  Otherwise, there
      // will be two virtual member functions with the same symbol
      // in the class and that leads to spurious hard-to-debug
      // change reports later down the road.
      if (i->second->get_symbol()
          || symbol_already_belongs_to_a_function(sym))
        continue;
 
      ABG_ASSERT(is_member_function(i->second));
      ABG_ASSERT(get_member_function_is_virtual(i->second));
      i->second->set_symbol(sym);
      // The function_decl now has an associated (public) ELF symbol so
      // it ought to be advertised as being public.
      i->second->set_is_in_public_symbol_table(true);
      // Add the function to the set of exported decls of the
      // current corpus.
      maybe_add_fn_to_exported_decls(i->second.get());
      if (do_log())
        cerr << "fixed up '"
         << i->second->get_pretty_representation()
         << "' with symbol '"
         << sym->get_id_string()
         << "'\n";
    }
 
    fns_with_no_symbol.clear();
  }
 
  /// Return a reference to the vector containing the types created
  /// during the binary analysis but that are not tied to a given
  /// DWARF DIE.
  ///
  /// @return reference to the vector containing the types created
  /// during the binary analysis but that are not tied to a given
  /// DWARF DIE.
  const vector<type_base_sptr>&
  types_to_canonicalize() const
  {return types_to_canonicalize_;}
 
  /// Clear the containers holding types to canonicalize.
  void
  clear_types_to_canonicalize()
  {
    types_to_canonicalize_.clear();
  }
 
  /// Types that were created but not tied to a particular DIE, must
  /// be scheduled for late canonicalization using this method.
  ///
  /// @param t the type to schedule for late canonicalization.
  void
  schedule_type_for_late_canonicalization(const type_base_sptr &t)
  {
    types_to_canonicalize_.push_back(t);
  }
 
  /// Canonicalize types which DIE offsets are stored in vectors on
  /// the side.  This is a sub-routine of
  /// reader::perform_late_type_canonicalizing().
  ///
  /// @param source where the DIE of the types to canonicalize are
  /// from.
  void
  canonicalize_types_scheduled()
  {
    tools_utils::timer cn_timer;
    if (do_log())
      {
    cerr << "going to canonicalize types";
    corpus_sptr c = corpus();
    if (c)
      cerr << " of corpus " << corpus()->get_path();
    cn_timer.start();
      }
 
    if (!types_to_canonicalize().empty())
      canonicalize_types(types_to_canonicalize().begin(),
             types_to_canonicalize().end(),
             [](const vector<type_base_sptr>::const_iterator& i)
             {return *i;});
 
    if (do_log())
      {
    cn_timer.stop();
    cerr << "finished canonicalizing types";
    corpus_sptr c = corpus();
    if (c)
      cerr << " of corpus " << corpus()->get_path();
    cerr << ": (" << cn_timer << ")\n";
      }
  }
 
  /// Compute the number of canonicalized and missed types in the late
  /// canonicalization phase.
  ///
  /// @param source where the DIEs of the canonicalized types are
  /// from.
  ///
  /// @param canonicalized the number of types that got canonicalized
  /// is added to the value already present in this parameter.
  ///
  /// @param missed the number of types scheduled for late
  /// canonicalization and which couldn't be canonicalized (for a
  /// reason) is added to the value already present in this parameter.
  void
  add_late_canonicalized_types_stats(size_t&        canonicalized,
                     size_t&        missed) const
  {
    for (auto t : types_to_canonicalize())
      {
    if (t->get_canonical_type())
      ++canonicalized;
    else
      ++missed;
      }
  }
 
  // Look at the types that need to be canonicalized after the
  // translation unit has been constructed and canonicalize them.
  void
  perform_late_type_canonicalizing()
  {
    canonicalize_types_scheduled();
 
    if (show_stats())
      {
    size_t num_canonicalized = 0, num_missed = 0, total = 0;
    add_late_canonicalized_types_stats(num_canonicalized,
                       num_missed);
    total = num_canonicalized + num_missed;
    cerr << "binary: "
         << elf_path()
         << "\n";
    cerr << "    # late canonicalized types: "
             << num_canonicalized;
        if (total)
          cerr << " (" << num_canonicalized * 100 / total << "%)";
        cerr << "\n"
         << "    # missed canonicalization opportunities: "
             << num_missed;
        if (total)
          cerr << " (" << num_missed * 100 / total << "%)";
        cerr << "\n";
      }
 
  }
 
  const die_tu_map_type&
  die_tu_map() const
  {return die_tu_map_;}
 
  die_tu_map_type&
  die_tu_map()
  {return die_tu_map_;}
 
  /// Getter for the map that associates a translation unit DIE to the
  /// vector of imported unit points that it contains.
  ///
  /// @param source where the DIEs are from.
  ///
  /// @return the map.
  const tu_die_imported_unit_points_map_type&
  tu_die_imported_unit_points_map(die_source source) const
  {return const_cast<reader*>(this)->tu_die_imported_unit_points_map(source);}
 
  /// Getter for the map that associates a translation unit DIE to the
  /// vector of imported unit points that it contains.
  ///
  /// @param source where the DIEs are from.
  ///
  /// @return the map.
  tu_die_imported_unit_points_map_type&
  tu_die_imported_unit_points_map(die_source source)
  {
    switch (source)
      {
      case PRIMARY_DEBUG_INFO_DIE_SOURCE:
    break;
      case ALT_DEBUG_INFO_DIE_SOURCE:
    return alt_tu_die_imported_unit_points_map_;
      case TYPE_UNIT_DIE_SOURCE:
    return type_units_tu_die_imported_unit_points_map_;
      case NO_DEBUG_INFO_DIE_SOURCE:
      case NUMBER_OF_DIE_SOURCES:
    // We cannot reach this point.
    ABG_ASSERT_NOT_REACHED;
      }
    return tu_die_imported_unit_points_map_;
  }
 
  /// Reset the current corpus being constructed.
  ///
  /// This actually deletes the current corpus being constructed.
  void
  reset_corpus()
  {corpus().reset();}
 
  /// Get the map that associates each DIE to its parent DIE.  This is
  /// for DIEs coming from the main debug info sections.
  ///
  /// @param source where the DIEs in the map come from.
  ///
  /// @return the DIE -> parent map.
  const offset_offset_map_type&
  die_parent_map(die_source source) const
  {return const_cast<reader*>(this)->die_parent_map(source);}
 
  /// Get the map that associates each DIE to its parent DIE.  This is
  /// for DIEs coming from the main debug info sections.
  ///
  /// @param source where the DIEs in the map come from.
  ///
  /// @return the DIE -> parent map.
  offset_offset_map_type&
  die_parent_map(die_source source)
  {
    switch (source)
      {
      case PRIMARY_DEBUG_INFO_DIE_SOURCE:
    break;
      case ALT_DEBUG_INFO_DIE_SOURCE:
    return alternate_die_parent_map_;
      case TYPE_UNIT_DIE_SOURCE:
    return type_section_die_parent_map();
      case NO_DEBUG_INFO_DIE_SOURCE:
      case NUMBER_OF_DIE_SOURCES:
    ABG_ASSERT_NOT_REACHED;
      }
    return primary_die_parent_map_;
  }
 
  const offset_offset_map_type&
  type_section_die_parent_map() const
  {return type_section_die_parent_map_;}
 
  offset_offset_map_type&
  type_section_die_parent_map()
  {return type_section_die_parent_map_;}
 
  /// Getter of the current translation unit.
  ///
  /// @return the current translation unit being constructed.
  const translation_unit_sptr&
  cur_transl_unit() const
  {return cur_tu_;}
 
  /// Getter of the current translation unit.
  ///
  /// @return the current translation unit being constructed.
  translation_unit_sptr&
  cur_transl_unit()
  {return cur_tu_;}
 
  /// Setter of the current translation unit.
  ///
  /// @param tu the current translation unit being constructed.
  void
  cur_transl_unit(translation_unit_sptr tu)
  {
    if (tu)
      cur_tu_ = tu;
  }
 
  /// Return the global scope of the current translation unit.
  ///
  /// @return the global scope of the current translation unit.
  const scope_decl_sptr&
  global_scope() const
  {return cur_transl_unit()->get_global_scope();}
 
  /// Return a scope that is nil.
  ///
  /// @return a scope that is nil.
  const scope_decl_sptr&
  nil_scope() const
  {return nil_scope_;}
 
  const scope_stack_type&
  scope_stack() const
  {return scope_stack_;}
 
  scope_stack_type&
  scope_stack()
  {return scope_stack_;}
 
  scope_decl*
  current_scope()
  {
    if (scope_stack().empty())
      {
    if (cur_transl_unit())
      scope_stack().push(cur_transl_unit()->get_global_scope().get());
      }
    return scope_stack().top();
  }
 
  list<var_decl_sptr>&
  var_decls_to_re_add_to_tree()
  {return var_decls_to_add_;}
 
  /// Test if a DIE represents a decl (function or variable) that has
  /// a symbol that is exported, whatever that means.  This is
  /// supposed to work for Linux Kernel binaries as well.
  ///
  /// This is useful to limit the amount of DIEs taken into account to
  /// the strict limit of what an ABI actually means.  Limiting the
  /// volume of DIEs analyzed this way is an important optimization to
  /// keep big binaries "manageable" by libabigail.
  ///
  /// @param DIE the die to consider.
  bool
  is_decl_die_with_exported_symbol(const Dwarf_Die *die)
  {
    if (!die || !die_is_decl(die))
      return false;
 
    bool result = false, address_found = false, symbol_is_exported = false;;
    Dwarf_Addr decl_symbol_address = 0;
 
    if (die_is_variable_decl(die))
      {
    if ((address_found = get_variable_address(die, decl_symbol_address)))
      symbol_is_exported =
        !!variable_symbol_is_exported(decl_symbol_address);
      }
    else if (die_is_function_decl(die))
      {
    if ((address_found = get_function_address(die, decl_symbol_address)))
      symbol_is_exported =
        !!function_symbol_is_exported(decl_symbol_address);
      }
 
    if (address_found)
      result = symbol_is_exported;
 
    return result;
  }
 
  /// This is a sub-routine of maybe_adjust_fn_sym_address and
  /// maybe_adjust_var_sym_address.
  ///
  /// Given an address that we got by looking at some debug
  /// information (e.g, a symbol's address referred to by a DWARF
  /// TAG), If the ELF file we are interested in is a shared library
  /// or an executable, then adjust the address to be coherent with
  /// where the executable (or shared library) is loaded.  That way,
  /// the address can be used to look for symbols in the executable or
  /// shared library.
  ///
  /// @return the adjusted address, or the same address as @p addr if
  /// it didn't need any adjustment.
  Dwarf_Addr
  maybe_adjust_address_for_exec_or_dyn(Dwarf_Addr addr) const
  {
    if (addr == 0)
      return addr;
 
    GElf_Ehdr eh_mem;
    GElf_Ehdr *elf_header = gelf_getehdr(elf_handle(), &eh_mem);
 
    if (elf_header->e_type == ET_DYN || elf_header->e_type == ET_EXEC)
      {
    Dwarf_Addr dwarf_elf_load_address = 0, elf_load_address = 0;
    ABG_ASSERT(get_binary_load_address(dwarf_elf_handle(),
                       dwarf_elf_load_address));
    ABG_ASSERT(get_binary_load_address(elf_handle(),
                       elf_load_address));
    if (dwarf_is_splitted()
        && (dwarf_elf_load_address != elf_load_address))
      // This means that in theory the DWARF and the executable are
      // not loaded at the same address.  And addr is meaningful
      // only in the context of the DWARF.
      //
      // So let's transform addr into an offset relative to where
      // the DWARF is loaded, and let's add that relative offset
      // to the load address of the executable.  That way, addr
      // becomes meaningful in the context of the executable and
      // can thus be used to compare against the address of
      // symbols of the executable, for instance.
      addr = addr - dwarf_elf_load_address + elf_load_address;
      }
 
    return addr;
  }
 
  /// For a relocatable (*.o) elf file, this function expects an
  /// absolute address, representing a function symbol.  It then
  /// extracts the address of the .text section from the symbol
  /// absolute address to get the relative address of the function
  /// from the beginning of the .text section.
  ///
  /// For executable or shared library, this function expects an
  /// address of a function symbol that was retrieved by looking at a
  /// DWARF "file".  The function thus adjusts the address to make it
  /// be meaningful in the context of the ELF file.
  ///
  /// In both cases, the address can then be compared against the
  /// st_value field of a function symbol from the ELF file.
  ///
  /// @param addr an adress for a function symbol that was retrieved
  /// from a DWARF file.
  ///
  /// @return the (possibly) adjusted address, or just @p addr if no
  /// adjustment took place.
  Dwarf_Addr
  maybe_adjust_fn_sym_address(Dwarf_Addr addr) const
  {
    if (addr == 0)
      return addr;
 
    Elf* elf = elf_handle();
    GElf_Ehdr eh_mem;
    GElf_Ehdr* elf_header = gelf_getehdr(elf, &eh_mem);
 
    if (elf_header->e_type == ET_REL)
      // We are looking at a relocatable file.  In this case, we don't
      // do anything because:
      //
      // 1/ the addresses from DWARF are absolute (relative to the
      // beginning of the relocatable file)
      //
      // 2/ The ELF symbol addresses that we store in our lookup
      // tables are translated from section-related to absolute as
      // well.  So we don't have anything to do at this point for
      // ET_REL files.
      ;
    else
      addr = maybe_adjust_address_for_exec_or_dyn(addr);
 
    return addr;
  }
 
  /// For a relocatable (*.o) elf file, this function expects an
  /// absolute address, representing a global variable symbol.  It
  /// then extracts the address of the {.data,.data1,.rodata,.bss}
  /// section from the symbol absolute address to get the relative
  /// address of the variable from the beginning of the data section.
  ///
  /// For executable or shared library, this function expects an
  /// address of a variable symbol that was retrieved by looking at a
  /// DWARF "file".  The function thus adjusts the address to make it
  /// be meaningful in the context of the ELF file.
  ///
  /// In both cases, the address can then be compared against the
  /// st_value field of a function symbol from the ELF file.
  ///
  /// @param addr an address for a global variable symbol that was
  /// retrieved from a DWARF file.
  ///
  /// @return the (possibly) adjusted address, or just @p addr if no
  /// adjustment took place.
  Dwarf_Addr
  maybe_adjust_var_sym_address(Dwarf_Addr addr) const
  {
    Elf* elf = elf_handle();
    GElf_Ehdr eh_mem;
    GElf_Ehdr* elf_header = gelf_getehdr(elf, &eh_mem);
 
    if (elf_header->e_type == ET_REL)
      // We are looking at a relocatable file.  In this case, we don't
      // do anything because:
      //
      // 1/ the addresses from DWARF are absolute (relative to the
      // beginning of the relocatable file)
      //
      // 2/ The ELF symbol addresses that we store in our lookup
      // tables are translated from section-related to absolute as
      // well.  So we don't have anything to do at this point for
      // ET_REL files.
      ;
    else
      addr = maybe_adjust_address_for_exec_or_dyn(addr);
 
    return addr;
  }
 
  /// Get the first exported function address in the set of addresses
  /// referred to by the DW_AT_ranges attribute of a given DIE.
  ///
  /// @param die the DIE we are considering.
  ///
  /// @param address output parameter.  This is set to the first
  /// address found in the sequence pointed to by the DW_AT_ranges
  /// attribute found on the DIE @p die, iff the function returns
  /// true.  Otherwise, no value is set into this output parameter.
  ///
  /// @return true iff the DIE @p die does have a DW_AT_ranges
  /// attribute and an address of an exported function was found in
  /// its sequence value.
  bool
  get_first_exported_fn_address_from_DW_AT_ranges(Dwarf_Die* die,
                          Dwarf_Addr& address) const
  {
    Dwarf_Addr base;
    Dwarf_Addr end_addr;
    ptrdiff_t offset = 0;
 
    do
      {
    Dwarf_Addr addr = 0, fn_addr = 0;
    if ((offset = dwarf_ranges(die, offset, &base, &addr, &end_addr)) >= 0)
      {
        fn_addr = maybe_adjust_fn_sym_address(addr);
        if (function_symbol_is_exported(fn_addr))
          {
        address = fn_addr;
        return true;
          }
      }
      } while (offset > 0);
    return false;
  }
 
  /// Get the address of the function.
  ///
  /// The address of the function is considered to be the value of the
  /// DW_AT_low_pc attribute, possibly adjusted (in relocatable files
  /// only) to not point to an absolute address anymore, but rather to
  /// the address of the function inside the .text segment.
  ///
  /// @param function_die the die of the function to consider.
  ///
  /// @param address the resulting address iff the function returns
  /// true.
  ///
  /// @return true if the function address was found.
  bool
  get_function_address(const Dwarf_Die* function_die, Dwarf_Addr& address) const
  {
    if (!die_address_attribute(const_cast<Dwarf_Die*>(function_die),
                   DW_AT_low_pc, address))
      // So no DW_AT_low_pc was found.  Let's see if the function DIE
      // has got a DW_AT_ranges attribute instead.  If it does, the
      // first address of the set of addresses represented by the
      // value of that DW_AT_ranges represents the function (symbol)
      // address we are looking for.
      if (!get_first_exported_fn_address_from_DW_AT_ranges
      (const_cast<Dwarf_Die*>(function_die),
       address))
    return false;
 
    address = maybe_adjust_fn_sym_address(address);
    return true;
  }
 
  /// Get the address of the global variable.
  ///
  /// The address of the global variable is considered to be the value
  /// of the DW_AT_location attribute, possibly adjusted (in
  /// relocatable files only) to not point to an absolute address
  /// anymore, but rather to the address of the global variable inside
  /// the data segment.
  ///
  /// @param variable_die the die of the function to consider.
  ///
  /// @param address the resulting address iff this function returns
  /// true.
  ///
  /// @return true if the variable address was found.
  bool
  get_variable_address(const Dwarf_Die* variable_die,
               Dwarf_Addr&  address) const
  {
    bool is_tls_address = false;
    if (!die_location_address(const_cast<Dwarf_Die*>(variable_die),
                  address, is_tls_address))
      return false;
    if (!is_tls_address)
      address = maybe_adjust_var_sym_address(address);
    return true;
  }
 
  /// Getter of the exported decls builder object.
  ///
  /// @return the exported decls builder.
  corpus::exported_decls_builder*
  exported_decls_builder()
  {return corpus()->get_exported_decls_builder().get();}
 
  /// Getter of the "load_all_types" flag.  This flag tells if all the
  /// types (including those not reachable by public declarations) are
  /// to be read and represented in the final ABI corpus.
  ///
  /// @return the load_all_types flag.
  bool
  load_all_types() const
  {return options().load_all_types;}
 
  /// Setter of the "load_all_types" flag.  This flag tells if all the
  /// types (including those not reachable by public declarations) are
  /// to be read and represented in the final ABI corpus.
  ///
  /// @param f the new load_all_types flag.
  void
  load_all_types(bool f)
  {options().load_all_types = f;}
 
  bool
  load_in_linux_kernel_mode() const
  {return options().load_in_linux_kernel_mode;}
 
  void
  load_in_linux_kernel_mode(bool f)
  {options().load_in_linux_kernel_mode = f;}
 
  /// Test if it's allowed to assume that the DWARF debug info has
  /// been factorized (for instance, with the DWZ tool) so that if two
  /// type DIEs originating from the .gnu_debugaltlink section have
  /// different offsets, they represent different types.
  ///
  /// @return true iff we can assume that the DWARF debug info has
  /// been factorized.
  bool
  leverage_dwarf_factorization() const
  {
    if (!leverage_dwarf_factorization_.has_value())
      {
    if (options().leverage_dwarf_factorization
        && elf_helpers::find_section_by_name(elf_handle(),
                         ".gnu_debugaltlink"))
      leverage_dwarf_factorization_ = true;
    else
      leverage_dwarf_factorization_ = false;
      }
    ABG_ASSERT(leverage_dwarf_factorization_.has_value());
 
    return *leverage_dwarf_factorization_;
  }
  /// Getter of the "show_stats" flag.
  ///
  /// This flag tells if we should emit statistics about various
  /// internal stuff.
  ///
  /// @return the value of the flag.
  bool
  show_stats() const
  {return options().show_stats;}
 
  /// Setter of the "show_stats" flag.
  ///
  /// This flag tells if we should emit statistics about various
  /// internal stuff.
  ///
  /// @param f the value of the flag.
  void
  show_stats(bool f)
  {options().show_stats = f;}
 
  /// Getter of the "do_log" flag.
  ///
  /// This flag tells if we should log about various internal
  /// details.
  ///
  /// return the "do_log" flag.
  bool
  do_log() const
  {return options().do_log;}
 
  /// Setter of the "do_log" flag.
  ///
  /// This flag tells if we should log about various internal details.
  ///
  /// @param f the new value of the flag.
  void
  do_log(bool f)
  {options().do_log = f;}
 
  /// Walk the DIEs under a given die and for each child, populate the
  /// die -> parent map to record the child -> parent relationship
  /// that
  /// exists between the child and the given die.
  ///
  /// The function also builds the vector of places where units are
  /// imported.
  ///
  /// This is done recursively as for each child DIE, this function
  /// walks its children as well.
  ///
  /// @param die the DIE whose children to walk recursively.
  ///
  /// @param source where the DIE @p die comes from.
  ///
  /// @param imported_units a vector containing all the offsets of the
  /// points where unit have been imported, under @p die.
  void
  build_die_parent_relations_under(Dwarf_Die*           die,
                   die_source           source,
                   imported_unit_points_type &  imported_units)
  {
    if (!die)
      return;
 
    offset_offset_map_type& parent_of = die_parent_map(source);
 
    Dwarf_Die child;
    if (dwarf_child(die, &child) != 0)
      return;
 
    do
      {
    parent_of[dwarf_dieoffset(&child)] = dwarf_dieoffset(die);
    if (dwarf_tag(&child) == DW_TAG_imported_unit)
      {
        Dwarf_Die imported_unit;
        if (die_die_attribute(&child, DW_AT_import, imported_unit)
        // If the imported_unit has a sub-tree, let's record
        // this point at which the sub-tree is imported into
        // the current debug info.
        //
        // Otherwise, if the imported_unit has no sub-tree,
        // there is no point in recording where a non-existent
        // sub-tree is being imported.
        //
        // Note that the imported_unit_points_type type below
        // expects the imported_unit to have a sub-tree.
        && die_has_children(&imported_unit))
          {
        die_source imported_unit_die_source = NO_DEBUG_INFO_DIE_SOURCE;
        ABG_ASSERT(get_die_source(imported_unit, imported_unit_die_source));
        imported_units.push_back
          (imported_unit_point(dwarf_dieoffset(&child),
                       imported_unit,
                       imported_unit_die_source));
          }
      }
    build_die_parent_relations_under(&child, source, imported_units);
      }
    while (dwarf_siblingof(&child, &child) == 0);
 
  }
 
  /// Determine if we do have to build a DIE -> parent map, depending
  /// on a given language.
  ///
  /// Some languages like C++, Ada etc, do have the concept of
  /// namespace and yet, the DIE data structure doesn't provide us
  /// with a way to get the parent namespace of a given DIE.  So for
  /// those languages, we need to build a DIE -> parent map so that we
  /// can get the namespace DIE (or more generally the scope DIE) of a given
  /// DIE as we need it.
  ///
  /// But then some more basic languages like C or assembly don't have
  /// that need.
  ///
  /// This function, depending on the language, tells us if we need to
  /// build the DIE -> parent map or not.
  ///
  /// @param lang the language to consider.
  ///
  /// @return true iff we need to build the DIE -> parent map for this
  /// language.
  bool
  do_we_build_die_parent_maps(translation_unit::language lang)
  {
    if (is_c_language(lang))
      return false;
 
    switch (lang)
      {
      case translation_unit::LANG_UNKNOWN:
#ifdef HAVE_DW_LANG_Mips_Assembler_enumerator
      case translation_unit::LANG_Mips_Assembler:
#endif
    return false;
      default:
    break;
      }
    return true;
  }
 
  /// Walk all the DIEs accessible in the debug info (and in the
  /// alternate debug info as well) and build maps representing the
  /// relationship DIE -> parent.  That is, make it so that we can get
  /// the parent for a given DIE.
  ///
  /// Note that the goal of this map is to be able to get the parent
  /// of a given DIE. This is to mainly to handle namespaces.  For instance,
  /// when we get a DIE of a type, and we want to build an internal
  /// representation for it, we need to get its fully qualified name.
  /// For that, we need to know what is the parent DIE of that type
  /// DIE, so that we can know what the namespace of that type is.
  ///
  /// Note that as the C language doesn't have namespaces (all types
  /// are defined in the same global namespace), this function doesn't
  /// build the DIE -> parent map if the current translation unit
  /// comes from C.  This saves time on big C ELF files with a lot of
  /// DIEs.
  void
  build_die_parent_maps()
  {
    bool we_do_have_to_build_die_parent_map = false;
    uint8_t address_size = 0;
    size_t header_size = 0;
    // Get the DIE of the current translation unit, look at it to get
    // its language. If that language is in C, then all types are in
    // the global namespace so we don't need to build the DIE ->
    // parent map.  So we dont build it in that case.
    for (Dwarf_Off offset = 0, next_offset = 0;
     (dwarf_next_unit(const_cast<Dwarf*>(dwarf_debug_info()),
              offset, &next_offset, &header_size,
              NULL, NULL, &address_size, NULL, NULL, NULL) == 0);
     offset = next_offset)
      {
    Dwarf_Off die_offset = offset + header_size;
    Dwarf_Die cu;
    if (!dwarf_offdie(const_cast<Dwarf*>(dwarf_debug_info()),
              die_offset, &cu))
      continue;
 
    uint64_t l = 0;
    die_unsigned_constant_attribute(&cu, DW_AT_language, l);
    translation_unit::language lang = dwarf_language_to_tu_language(l);
    if (do_we_build_die_parent_maps(lang))
      we_do_have_to_build_die_parent_map = true;
      }
 
    if (!we_do_have_to_build_die_parent_map)
      return;
 
    // Build the DIE -> parent relation for DIEs coming from the
    // .debug_info section in the alternate debug info file.
    die_source source = ALT_DEBUG_INFO_DIE_SOURCE;
    for (Dwarf_Off offset = 0, next_offset = 0;
     (dwarf_next_unit(const_cast<Dwarf*>(alternate_dwarf_debug_info()),
              offset, &next_offset, &header_size,
              NULL, NULL, &address_size, NULL, NULL, NULL) == 0);
     offset = next_offset)
      {
    Dwarf_Off die_offset = offset + header_size;
    Dwarf_Die cu;
    if (!dwarf_offdie(const_cast<Dwarf*>(alternate_dwarf_debug_info()),
              die_offset, &cu))
      continue;
    cur_tu_die(&cu);
 
    imported_unit_points_type& imported_units =
      tu_die_imported_unit_points_map(source)[die_offset] =
      imported_unit_points_type();
    build_die_parent_relations_under(&cu, source, imported_units);
      }
 
    // Build the DIE -> parent relation for DIEs coming from the
    // .debug_info section of the main debug info file.
    source = PRIMARY_DEBUG_INFO_DIE_SOURCE;
    address_size = 0;
    header_size = 0;
    for (Dwarf_Off offset = 0, next_offset = 0;
     (dwarf_next_unit(const_cast<Dwarf*>(dwarf_debug_info()),
              offset, &next_offset, &header_size,
              NULL, NULL, &address_size, NULL, NULL, NULL) == 0);
     offset = next_offset)
      {
    Dwarf_Off die_offset = offset + header_size;
    Dwarf_Die cu;
    if (!dwarf_offdie(const_cast<Dwarf*>(dwarf_debug_info()),
              die_offset, &cu))
      continue;
    cur_tu_die(&cu);
    imported_unit_points_type& imported_units =
      tu_die_imported_unit_points_map(source)[die_offset] =
      imported_unit_points_type();
    build_die_parent_relations_under(&cu, source, imported_units);
      }
 
    // Build the DIE -> parent relation for DIEs coming from the
    // .debug_types section.
    source = TYPE_UNIT_DIE_SOURCE;
    address_size = 0;
    header_size = 0;
    uint64_t type_signature = 0;
    Dwarf_Off type_offset;
    for (Dwarf_Off offset = 0, next_offset = 0;
     (dwarf_next_unit(const_cast<Dwarf*>(dwarf_debug_info()),
              offset, &next_offset, &header_size,
              NULL, NULL, &address_size, NULL,
              &type_signature, &type_offset) == 0);
     offset = next_offset)
      {
    Dwarf_Off die_offset = offset + header_size;
    Dwarf_Die cu;
 
    if (!dwarf_offdie_types(const_cast<Dwarf*>(dwarf_debug_info()),
                die_offset, &cu))
      continue;
    cur_tu_die(&cu);
    imported_unit_points_type& imported_units =
      tu_die_imported_unit_points_map(source)[die_offset] =
      imported_unit_points_type();
    build_die_parent_relations_under(&cu, source, imported_units);
      }
  }
};// end class reader.
 
/// The type of the aggregates being compared during a DIE comparison.
///
/// This encapsulates the stack of aggregates being compared at any
/// single point.
///
/// This is useful to detect "comparison cycles" and thus avoid the
/// resulting infinite loops.
///
/// This is also useful for implementing a very important optimization
/// that takes place during the canonicalization
struct offset_pairs_stack_type
{
  // The DWARF DWARF reader that is useful for so many things.
  const reader& rdr_;
  // The set of types that are being compared.  This is to speed up
  // searches.
  offset_pair_set_type set_;
  // The stack of  types that are being compared.  The top of the
  // stack is the back of the vector.
  offset_pair_vector_type vect_;
  // A map that associates a redundant type pair to the vector of
  // types that depends on it.
  offset_pair_vect_map_type redundant_types_;
  // A map that associates a dependant type to the vector of redundant
  // types it depends on.
  offset_pair_vect_map_type dependant_types_;
 
  offset_pairs_stack_type(const reader& rdr)
    : rdr_ (rdr)
  {}
 
  /// Add a pair of types being compared to the stack of aggregates
  /// being compared.
  ///
  /// @param p the pair of offsets of the type DIEs to consider.
  void
  add(const offset_pair_type& p)
  {
    set_.insert(p);
    vect_.push_back(p);
  }
 
  /// Erase a pair of types being compared from the stack of
  /// aggregates being compared.
  ///
  /// @param p the pair of offsets of the type DIEs to consider.
  ///
  /// @return true iff @p was found and erased from the stack.
  bool
  erase(const offset_pair_type& p)
  {
    if (set_.erase(p))
      {
    offset_pair_vector_type::iterator i;
 
    for (i = vect_.begin();i < vect_.end(); ++i)
      if (*i == p)
        break;
 
    if (i != vect_.end())
      vect_.erase(i);
 
    return true;
      }
 
    return false;
  }
 
  /// Test if a pair of type DIEs is part of the stack of type DIEs
  /// being compared.
  ///
  /// @param p the pair of offsets of the type DIEs to consider.
  ///
  /// @return true iff @p was found in the stack of types being
  /// compared.
  bool
  contains(const offset_pair_type &p) const
  {
    if (set_.find(p) == set_.end())
      return false;
    return true;
  }
 
  /// Get the set of comparison pair that depends on a given
  /// comparison pair.
  ///
  /// A comparison pair T{t1,t2} depends on a comparison pair P{p1,p2}
  /// if p1 is a subtype of t1 and p2 is a subtype of t2.  In other
  /// words, the pair T appears in the comparison stack BEFORE the
  /// pair P.
  ///
  /// So, this function returns the vector of comparison pairs that
  /// appear in the comparison stack AFTER a given comparison pair.
  ///
  /// @param p the comparison pair to consider.
  ///
  /// @param pairs out parameter.  This is filled with the comparison
  /// pairs that depend on @p, iff the function returns true.
  ///
  /// @return true iff comparison pairs depending on @p have been
  /// found and collected in @pairs.
  bool
  get_pairs_that_depend_on(const offset_pair_type& p,
               offset_pair_vector_type& pairs) const
  {
    bool result = false;
    if (!contains(p))
      return result;
 
    // First, get an iterator on the position of 'p'.
    offset_pair_vector_type::const_iterator i;
    for (i = vect_.begin(); i != vect_.end(); ++i)
      if (*i == p)
    break;
 
    if (i == vect_.end())
      return result;
 
    // Then, harvest all the comparison pairs that come after the
    // position of 'p'.
    for (++i; i != vect_.end(); ++i)
      {
    pairs.push_back(*i);
    result = true;
      }
 
    return result;
  }
 
  /// Record the fact that a set of comparison pairs depends on a
  /// given comparison pair.
  ///
  /// Set a map that associates each dependant comparison pair to the
  /// pair it depends on.
  ///
  /// @param p the comparison pair that the set depends on.
  ///
  /// @param dependant_types the set of types that depends on @p.
  void
  record_dependant_types(const offset_pair_type& p,
             const offset_pair_vector_type& dependant_types)
  {
    for (auto type_pair : dependant_types)
      dependant_types_[type_pair].push_back(p);
  }
 
  /// Record a comparison pair as being redundant.
  ///
  ///
  /// @param p the comparison pair to record as redundant.
  void
  record_redundant_type_die_pair(const offset_pair_type& p)
  {
    offset_pair_vector_type dependant_types;
    get_pairs_that_depend_on(p, dependant_types);
 
    // First, record the relationship "p -> [pairs that depend on p]".
    auto it = redundant_types_.find(p);
    if (it == redundant_types_.end())
      {
    auto entry = std::make_pair(p, dependant_types);
    redundant_types_.insert(entry);
      }
    else
      it->second.insert(it->second.end(),
            dependant_types.begin(),
            dependant_types.end());
 
    // For each dependant type pair, record the association:
    // dependant_pair --> [vect of redundant types]
    record_dependant_types(p, dependant_types);
  }
 
  /// Test if a given pair has been detected as redundant.
  ///
  /// @param p the pair of DIEs to consider.
  ///
  /// @return iff @p is redundant.
  bool
  is_redundant(const offset_pair_type& p)
  {
    auto i = redundant_types_.find(p);
    if (i != redundant_types_.end())
      return true;
    return false;
  }
 
  /// Test if a given pair is dependant on at least a redundant type.
  ///
  /// @param p the pair to consider.
  ///
  /// @return true iff @p depends on a redundant type.
  bool
  depends_on_redundant_types(const offset_pair_type& p)
  {
    auto i = dependant_types_.find(p);
    if (i == dependant_types_.end())
      return false;
    return true;
  }
 
  /// Remove a redundant pair from the system.
  ///
  /// This needs updating the system to also remove the dependant
  /// types that depend on the redundant pair (if they depend only on
  /// that redundant pair).
  ///
  /// @param p the pair to consider.
  ///
  /// @param erase_canonical_die_offset if true then erase the cached
  /// comparison results for the redundant pair and its dependant
  /// types.
  void
  erase_redundant_type_pair_entry(const offset_pair_type& p,
                  bool erase_cached_results = false)
  {
    // First, update the dependant types that depend on the redundant
    // type pair
    auto redundant_type = redundant_types_.find(p);
    if (redundant_type != redundant_types_.end())
      {
    for (auto dependant_type : redundant_type->second)
      {
        // Each dependant_type depends on the redundant type 'p',
        // among others.
        auto dependant_types_it = dependant_types_.find(dependant_type);
        ABG_ASSERT(dependant_types_it != dependant_types_.end());
        // Erase the redundant type 'p' from the redundant types
        // that dependant_type depends on.
        {
          auto i = dependant_types_it->second.begin();
          for (; i!= dependant_types_it->second.end();++i)
        if (*i == p)
          break;
          if (i != dependant_types_it->second.end())
        dependant_types_it->second.erase(i);
        }
        // If the dependant type itself doesn't depend on ANY
        // redundant type anymore, then remove the depend type
        // from the map of the dependant types.
        if (dependant_types_it->second.empty())
          {
        if (erase_cached_results)
          rdr_.die_comparison_results_.erase(dependant_type);
        dependant_types_.erase(dependant_types_it);
          }
      }
      }
    if (erase_cached_results)
      rdr_.die_comparison_results_.erase(p);
    redundant_types_.erase(p);
  }
 
  /// If a comparison pair has been detected as redundant, stop
  /// tracking it as well as its dependant pairs.  That will
  /// essentially make it impossible to reset/cancel the canonical
  /// propagated types for those depdant pairs, but will also save
  /// ressources.
  ///
  /// @param p the comparison pair to consider.
  void
  confirm_canonical_propagated_type(const offset_pair_type& p)
  {erase_redundant_type_pair_entry(p, /*erase_cached_results=*/true);}
 
  /// Walk the types that depend on a comparison pair and cancel their
  /// canonical-propagate-type, that means remove their canonical
  /// types and mark them as not being canonically-propagated.  Also,
  /// erase their cached comparison results that was likely set to
  /// COMPARISON_RESULT_UNKNOWN.
  ///
  /// @param p the pair to consider.
  void
  cancel_canonical_propagated_type(const offset_pair_type& p)
  {
    offset_pair_set_type dependant_types;
    get_dependant_types(p, dependant_types, /*transitive_closure=*/true);
    for (auto dependant_type : dependant_types)
      {
    // If this dependant type was canonical-type-propagated then
    // erase that canonical type.
    if (rdr_.propagated_types_.find(dependant_type)
        != rdr_.propagated_types_.end())
      {
        rdr_.erase_canonical_die_offset(dependant_type.first.offset_,
                         dependant_type.first.source_,
                         /*die_as_type=*/true);
        rdr_.propagated_types_.erase(dependant_type);
        rdr_.cancelled_propagation_count_++;
      }
    // Update the cached result.  We know the comparison result
    // must now be different.
    auto comp_result_it = rdr_.die_comparison_results_.find(dependant_type);
    if (comp_result_it != rdr_.die_comparison_results_.end())
      comp_result_it->second= COMPARISON_RESULT_DIFFERENT;
      }
 
    // Update the cached result of the root type to cancel too.
    auto comp_result_it = rdr_.die_comparison_results_.find(p);
    if (comp_result_it != rdr_.die_comparison_results_.end())
      {
    // At this point, the result of p is either
    // COMPARISON_RESULT_UNKNOWN (if we cache comparison
    // results of that kind) or COMPARISON_RESULT_DIFFERENT.
    // Make sure it's the cached result is now
    // COMPARISON_RESULT_DIFFERENT.
    if (comp_result_it->second == COMPARISON_RESULT_UNKNOWN)
      comp_result_it->second= COMPARISON_RESULT_DIFFERENT;
    ABG_ASSERT(comp_result_it->second == COMPARISON_RESULT_DIFFERENT);
      }
 
    if (rdr_.propagated_types_.find(p) != rdr_.propagated_types_.end())
      {
    rdr_.erase_canonical_die_offset(p.first.offset_,
                     p.first.source_,
                     /*die_as_type=*/true);
    rdr_.propagated_types_.erase(p);
    rdr_.cancelled_propagation_count_++;
      }
  }
 
  /// Get the set of comparison pairs that depend on a given pair.
  ///
  /// @param p the pair to consider.
  ///
  /// @param result this is set to the pairs that depend on @p, iff
  /// the function returned true.
  ///
  /// @param transitive_closure if set to true, the transitive closure
  /// of the @result is set to it.
  ///
  /// @return true iff @result could be filled with the dependant
  /// types.
  bool
  get_dependant_types(const offset_pair_type& p,
              offset_pair_set_type& result,
              bool transitive_closure = false)
  {
    auto i = redundant_types_.find(p);
    if (i != redundant_types_.end())
      {
    for (auto dependant_type : i->second)
      if (result.find(dependant_type) == result.end())
        {
          result.insert(dependant_type);
          if (transitive_closure)
        get_dependant_types(p, result, /*transitive_closure=*/true);
        }
    return true;
      }
    return false;
  }
}; // end struct offset_pairs_stack_type
 
static type_or_decl_base_sptr
build_ir_node_from_die(reader&  rdr,
               Dwarf_Die*   die,
               scope_decl*  scope,
               bool     called_from_public_decl,
               size_t       where_offset,
               bool     is_declaration_only = true,
               bool     is_required_decl_spec = false);
 
static type_or_decl_base_sptr
build_ir_node_from_die(reader&  rdr,
               Dwarf_Die*   die,
               bool     called_from_public_decl,
               size_t       where_offset);
 
static class_decl_sptr
add_or_update_class_type(reader&     rdr,
             Dwarf_Die*  die,
             scope_decl*     scope,
             bool        is_struct,
             class_decl_sptr klass,
             bool        called_from_public_decl,
             size_t      where_offset,
             bool        is_declaration_only);
 
static union_decl_sptr
add_or_update_union_type(reader&     rdr,
             Dwarf_Die*  die,
             scope_decl*     scope,
             union_decl_sptr union_type,
             bool        called_from_public_decl,
             size_t      where_offset,
             bool        is_declaration_only);
 
static decl_base_sptr
build_ir_node_for_void_type(reader& rdr);
 
static decl_base_sptr
build_ir_node_for_variadic_parameter_type(reader &rdr);
 
static function_decl_sptr
build_function_decl(reader& rdr,
            Dwarf_Die*      die,
            size_t      where_offset,
            function_decl_sptr  fn);
 
static bool
function_is_suppressed(const reader& rdr,
               const scope_decl* scope,
               Dwarf_Die *function_die,
               bool is_declaration_only);
 
static function_decl_sptr
build_or_get_fn_decl_if_not_suppressed(reader&  rdr,
                       scope_decl   *scope,
                       Dwarf_Die    *die,
                       size_t   where_offset,
                       bool is_declaration_only,
                       function_decl_sptr f);
 
static var_decl_sptr
build_var_decl(reader&  rdr,
           Dwarf_Die    *die,
           size_t       where_offset,
           var_decl_sptr    result = var_decl_sptr());
 
static var_decl_sptr
build_or_get_var_decl_if_not_suppressed(reader& rdr,
                    scope_decl  *scope,
                    Dwarf_Die   *die,
                    size_t  where_offset,
                    var_decl_sptr   res = var_decl_sptr(),
                    bool is_required_decl_spec = false);
static bool
variable_is_suppressed(const reader& rdr,
               const scope_decl* scope,
               Dwarf_Die *variable_die,
               bool is_required_decl_spec = false);
 
static void
finish_member_function_reading(Dwarf_Die*           die,
                   const function_decl_sptr&    f,
                   const class_or_union_sptr    klass,
                   reader&          rdr);
 
/// Test if a given DIE is anonymous
///
/// @param die the DIE to consider.
///
/// @return true iff @p die is anonymous.
static bool
die_is_anonymous(const Dwarf_Die* die)
{
  Dwarf_Attribute attr;
  if (!dwarf_attr_integrate(const_cast<Dwarf_Die*>(die), DW_AT_name, &attr))
    return true;
  return false;
}
 
/// Test if a DIE is an anonymous data member, aka, "unnamed field".
///
/// Unnamed fields are specified at
/// https://gcc.gnu.org/onlinedocs/gcc/Unnamed-Fields.html.
///
/// @param die the DIE to consider.
///
/// @return true iff @p die is an anonymous data member.
static bool
die_is_anonymous_data_member(const Dwarf_Die* die)
{
  if (!die
      || dwarf_tag(const_cast<Dwarf_Die*>(die)) != DW_TAG_member
      || !die_name(die).empty())
    return false;
 
  Dwarf_Die type_die;
  if (!die_die_attribute(die, DW_AT_type, type_die))
    return false;
 
  if (dwarf_tag(&type_die) != DW_TAG_structure_type
      && dwarf_tag(&type_die) != DW_TAG_union_type)
  return false;
 
  return true;
}
 
/// Get the value of an attribute that is supposed to be a string, or
/// an empty string if the attribute could not be found.
///
/// @param die the DIE to get the attribute value from.
///
/// @param attr_name the attribute name.  Must come from dwarf.h and
/// be an enumerator representing an attribute like, e.g, DW_AT_name.
///
/// @return the string representing the value of the attribute, or an
/// empty string if no string attribute could be found.
static string
die_string_attribute(const Dwarf_Die* die, unsigned attr_name)
{
  if (!die)
    return "";
 
  Dwarf_Attribute attr;
  if (!dwarf_attr_integrate(const_cast<Dwarf_Die*>(die), attr_name, &attr))
    return "";
 
  const char* str = dwarf_formstring(&attr);
  return str ? str : "";
}
 
/// Get the value of an attribute that is supposed to be a string, or
/// an empty string if the attribute could not be found.
///
/// @param die the DIE to get the attribute value from.
///
/// @param attr_name the attribute name.  Must come from dwarf.h and
/// be an enumerator representing an attribute like, e.g, DW_AT_name.
///
/// @return the char* representing the value of the attribute, or an
/// empty string if no string attribute could be found.
static const char*
die_char_str_attribute(const Dwarf_Die* die, unsigned attr_name)
{
  if (!die)
    return nullptr;
 
  Dwarf_Attribute attr;
  if (!dwarf_attr_integrate(const_cast<Dwarf_Die*>(die), attr_name, &attr))
    return nullptr;
 
  const char* str = dwarf_formstring(&attr);
  return str;
}
 
/// Get the value of an attribute that is supposed to be an unsigned
/// constant.
///
/// @param die the DIE to read the information from.
///
/// @param attr_name the DW_AT_* name of the attribute.  Must come
/// from dwarf.h and be an enumerator representing an attribute like,
/// e.g, DW_AT_decl_line.
///
///@param cst the output parameter that is set to the value of the
/// attribute @p attr_name.  This parameter is set iff the function
/// return true.
///
/// @return true if there was an attribute of the name @p attr_name
/// and with a value that is a constant, false otherwise.
static bool
die_unsigned_constant_attribute(const Dwarf_Die*    die,
                unsigned    attr_name,
                uint64_t&   cst)
{
  if (!die)
    return false;
 
  Dwarf_Attribute attr;
  Dwarf_Word result = 0;
  if (!dwarf_attr_integrate(const_cast<Dwarf_Die*>(die), attr_name, &attr)
      || dwarf_formudata(&attr, &result))
    return false;
 
  cst = result;
  return true;
}
 
/// Read a signed constant value from a given attribute.
///
/// The signed constant expected must be of constant form.
///
/// @param die the DIE to get the attribute from.
///
/// @param attr_name the attribute name.
///
/// @param cst the resulting signed constant read.
///
/// @return true iff a signed constant attribute of the name @p
/// attr_name was found on the DIE @p die.
static bool
die_signed_constant_attribute(const Dwarf_Die *die,
                  unsigned  attr_name,
                  int64_t&  cst)
{
  if (!die)
    return false;
 
  Dwarf_Attribute attr;
  Dwarf_Sword result = 0;
  if (!dwarf_attr_integrate(const_cast<Dwarf_Die*>(die), attr_name, &attr)
      || dwarf_formsdata(&attr, &result))
    return false;
 
  cst = result;
  return true;
}
 
/// Read the value of a constant attribute that is either signed or
/// unsigned into a array_type_def::subrange_type::bound_value value.
///
/// The bound_value instance will capture the actual signedness of the
/// read attribute.
///
/// @param die the DIE from which to read the value of the attribute.
///
/// @param attr_name the attribute name to consider.
///
/// @param is_signed true if the attribute value has to read as
/// signed.
///
/// @param value the resulting value read from attribute @p attr_name
/// on DIE @p die.
///
/// @return true iff DIE @p die has an attribute named @p attr_name
/// with a constant value.
static bool
die_constant_attribute(const Dwarf_Die *die,
               unsigned attr_name,
               bool is_signed,
               array_type_def::subrange_type::bound_value &value)
{
  if (!is_signed)
    {
      uint64_t l = 0;
      if (!die_unsigned_constant_attribute(die, attr_name, l))
    return false;
      value.set_unsigned(l);
    }
  else
    {
      int64_t l = 0;
      if (!die_signed_constant_attribute(die, attr_name, l))
    return false;
      value.set_signed(l);
    }
  return true;
}
 
/// Test if a given DWARF form is DW_FORM_strx{1,4}.
///
/// Unfortunaly, the DW_FORM_strx{1,4} are enumerators of an untagged
/// enum in dwarf.h so we have to use an unsigned int for the form,
/// grrr.
///
/// @param form the form to consider.
///
/// @return true iff @p form is DW_FORM_strx{1,4}.
static bool
form_is_DW_FORM_strx(unsigned form)
{
  if (form)
    {
#if defined HAVE_DW_FORM_strx1      \
  && defined HAVE_DW_FORM_strx2 \
  && defined HAVE_DW_FORM_strx3 \
  && defined HAVE_DW_FORM_strx4
      if (form == DW_FORM_strx1
      || form == DW_FORM_strx2
      || form == DW_FORM_strx3
      ||form == DW_FORM_strx4)
    return true;
#endif
    }
  return false;
}
 
/// Test if a given DWARF form is DW_FORM_line_strp.
///
/// Unfortunaly, the DW_FORM_line_strp is an enumerator of an untagged
/// enum in dwarf.h so we have to use an unsigned int for the form,
/// grrr.
///
/// @param form the form to consider.
///
/// @return true iff @p form is DW_FORM_line_strp.
static bool
form_is_DW_FORM_line_strp(unsigned form)
{
  if (form)
    {
#if defined HAVE_DW_FORM_line_strp
      if (form == DW_FORM_line_strp)
    return true;
#endif
    }
  return false;
}
 
/// Get the value of a DIE attribute; that value is meant to be a
/// flag.
///
/// @param die the DIE to get the attribute from.
///
/// @param attr_name the DW_AT_* name of the attribute.  Must come
/// from dwarf.h and be an enumerator representing an attribute like,
/// e.g, DW_AT_external.
///
/// @param flag the output parameter to store the flag value into.
/// This is set iff the function returns true.
///
/// @param recursively if true, the function looks through the
/// possible DW_AT_specification and DW_AT_abstract_origin attribute
/// all the way down to the initial DIE that is cloned and look on
/// that DIE to see if it has the @p attr_name attribute.
///
/// @return true if the DIE has a flag attribute named @p attr_name,
/// false otherwise.
static bool
die_flag_attribute(const Dwarf_Die* die,
           unsigned attr_name,
           bool& flag,
           bool recursively = true)
{
  Dwarf_Attribute attr;
  if (recursively
      ? !dwarf_attr_integrate(const_cast<Dwarf_Die*>(die), attr_name, &attr)
      : !dwarf_attr(const_cast<Dwarf_Die*>(die), attr_name, &attr))
    return false;
 
  bool f = false;
  if (dwarf_formflag(&attr, &f))
    return false;
 
  flag = f;
  return true;
}
 
/// Get the mangled name from a given DIE.
///
/// @param die the DIE to read the mangled name from.
///
/// @return the mangled name if it's present in the DIE, or just an
/// empty string if it's not.
static string
die_linkage_name(const Dwarf_Die* die)
{
  if (!die)
    return "";
 
  string linkage_name = die_string_attribute(die, DW_AT_linkage_name);
  if (linkage_name.empty())
    linkage_name = die_string_attribute(die, DW_AT_MIPS_linkage_name);
  return linkage_name;
}
 
/// Get the file path that is the value of the DW_AT_decl_file
/// attribute on a given DIE, if the DIE is a decl DIE having that
/// attribute.
///
/// @param die the DIE to consider.
///
/// @return a string containing the file path that is the logical
/// value of the DW_AT_decl_file attribute.  If the DIE @p die
/// doesn't have a DW_AT_decl_file attribute, then the return value is
/// just an empty string.
static string
die_decl_file_attribute(const Dwarf_Die* die)
{
  if (!die)
    return "";
 
  const char* str = dwarf_decl_file(const_cast<Dwarf_Die*>(die));
 
  return str ? str : "";
}
 
/// Get the value of an attribute which value is supposed to be a
/// reference to a DIE.
///
/// @param die the DIE to read the value from.
///
/// @param attr_name the DW_AT_* attribute name to read.
///
/// @param result the DIE resulting from reading the attribute value.
/// This is set iff the function returns true.
///
/// @param recursively if true, the function looks through the
/// possible DW_AT_specification and DW_AT_abstract_origin attribute
/// all the way down to the initial DIE that is cloned and look on
/// that DIE to see if it has the @p attr_name attribute.
///
/// @return true if the DIE @p die contains an attribute named @p
/// attr_name that is a DIE reference, false otherwise.
static bool
die_die_attribute(const Dwarf_Die* die,
          unsigned attr_name,
          Dwarf_Die& result,
          bool recursively)
{
  Dwarf_Attribute attr;
  if (recursively
      ? !dwarf_attr_integrate(const_cast<Dwarf_Die*>(die), attr_name, &attr)
      : !dwarf_attr(const_cast<Dwarf_Die*>(die), attr_name, &attr))
    return false;
 
  return dwarf_formref_die(&attr, &result);
}
 
/// Test if a subrange DIE indirectly references another subrange DIE
/// through a given attribute.
///
/// A DW_TAG_subrange_type DIE can have its DW_AT_{lower,upper}_bound
/// attribute be a reference to either a data member or a variable
/// which type is itself a DW_TAG_subrange_type.  This latter subrange
/// DIE is said to be "indirectly referenced" by the former subrange
/// DIE.  In that case, the DW_AT_{lower,upper}_bound of the latter is
/// the value we want for the DW_AT_upper_bound of the former.
///
/// This function tests if the former subrange DIE does indirectly
/// reference another subrange DIE through a given attribute (not
/// necessarily DW_AT_upper_bound).
///
/// @param die the DIE to consider.  Note that It must be a
/// DW_TAG_subrange_type.
///
/// @param attr_name the name of the attribute to look through for the
/// indirectly referenced subrange DIE.
///
/// @param referenced_subrange if the function returns true, then the
/// argument of this parameter is set to the indirectly referenced
/// DW_TAG_subrange_type DIE.
///
/// @return true iff @p DIE indirectly references a subrange DIE
/// through the attribute @p attr_name.
static bool
subrange_die_indirectly_references_subrange_die(const Dwarf_Die *die,
                        unsigned attr_name,
                        Dwarf_Die& referenced_subrange)
{
  bool result = false;
 
  if (dwarf_tag(const_cast<Dwarf_Die*>(die)) != DW_TAG_subrange_type)
    return result;
 
  Dwarf_Die referenced_die;
  if (die_die_attribute(die, attr_name, referenced_die))
    {
      unsigned tag = dwarf_tag(&referenced_die);
      if ( tag == DW_TAG_member || tag == DW_TAG_variable)
    {
      Dwarf_Die type_die;
      if (die_die_attribute(&referenced_die, DW_AT_type, type_die))
        {
          tag = dwarf_tag(&type_die);
          if (tag == DW_TAG_subrange_type)
        {
          memcpy(&referenced_subrange, &type_die, sizeof(type_die));
          result = true;
        }
        }
    }
    }
  return result;
}
 
/// Return the bound value of subrange die by looking at an indirectly
/// referenced subrange DIE.
///
/// A DW_TAG_subrange_type DIE can have its DW_AT_{lower,upper}_bound
/// attribute be a reference to either a data member or a variable
/// which type is itself a DW_TAG_subrange_type.  This latter subrange
/// DIE is said to be "indirectly referenced" by the former subrange
/// DIE.  In that case, the DW_AT_{lower,upper}_bound of the latter is
/// the value we want for the DW_AT_{lower,upper}_bound of the former.
///
/// This function gets the DW_AT_{lower,upper}_bound value of a
/// subrange type by looking at the DW_AT_{lower,upper}_bound value of
/// the indirectly referenced subrange type, if it exists.
///
/// @param die the subrange DIE to consider.
///
/// @param attr_name the name of the attribute to consider, typically,
/// DW_AT_{lower,upper}_bound.
///
/// @param v the found value, iff this function returned true.
///
/// @param is_signed, this is set to true if @p v is signed.  This
/// parameter is set at all only if the function returns true.
///
/// @return true iff the DW_AT_{lower,upper}_bound was found on the
/// indirectly referenced subrange type.
static bool
subrange_die_indirect_bound_value(const Dwarf_Die *die,
                  unsigned attr_name,
                  array_type_def::subrange_type::bound_value& v,
                  bool& is_signed)
{
  bool result = false;
 
  if (dwarf_tag(const_cast<Dwarf_Die*>(die)) != DW_TAG_subrange_type)
    return result;
 
  Dwarf_Die subrange_die;
  if (subrange_die_indirectly_references_subrange_die(die, attr_name,
                              subrange_die))
    {
      if (die_constant_attribute(&subrange_die, attr_name, is_signed, v))
    result = true;
    }
  return result;
}
 
/// Read and return an addresss class attribute from a given DIE.
///
/// @param die the DIE to consider.
///
/// @param attr_name the name of the address class attribute to read
/// the value from.
///
/// @param the resulting address.
///
/// @return true iff the attribute could be read, was of the expected
/// address class and could thus be translated into the @p result.
static bool
die_address_attribute(Dwarf_Die* die, unsigned attr_name, Dwarf_Addr& result)
{
  Dwarf_Attribute attr;
  if (!dwarf_attr_integrate(die, attr_name, &attr))
    return false;
  return dwarf_formaddr(&attr, &result) == 0;
}
 
/// Returns the source location associated with a decl DIE.
///
/// @param rdr the @ref reader to use.
///
/// @param die the DIE the read the source location from.
///
/// @return the location associated with @p die.
static location
die_location(const reader& rdr, const Dwarf_Die* die)
{
  if (!die)
    return location();
 
  string file = die_decl_file_attribute(die);
  uint64_t line = 0;
  die_unsigned_constant_attribute(die, DW_AT_decl_line, line);
 
  if (!file.empty() && line != 0)
    {
      translation_unit_sptr tu = rdr.cur_transl_unit();
      location l = tu->get_loc_mgr().create_new_location(file, line, 1);
      return l;
    }
  return location();
}
 
/// Return a copy of the name of a DIE.
///
/// @param die the DIE to consider.
///
/// @return a copy of the name of the DIE.
static string
die_name(const Dwarf_Die* die)
{
  string name = die_string_attribute(die, DW_AT_name);
  return name;
}
 
/// Return the location, the name and the mangled name of a given DIE.
///
/// @param rdr the DWARF reader to use.
///
/// @param die the DIE to read location and names from.
///
/// @param loc the location output parameter to set.
///
/// @param name the name output parameter to set.
///
/// @param linkage_name the linkage_name output parameter to set.
static void
die_loc_and_name(const reader&  rdr,
         Dwarf_Die*     die,
         location&      loc,
         string&        name,
         string&        linkage_name)
{
  loc = die_location(rdr, die);
  name = die_name(die);
  linkage_name = die_linkage_name(die);
}
 
/// Get the size of a (type) DIE as the value for the parameter
/// DW_AT_byte_size or DW_AT_bit_size.
///
/// @param die the DIE to read the information from.
///
/// @param size the resulting size in bits.  This is set iff the
/// function return true.
///
/// @return true if the size attribute was found.
static bool
die_size_in_bits(const Dwarf_Die* die, uint64_t& size)
{
  if (!die)
    return false;
 
  uint64_t byte_size = 0, bit_size = 0;
 
  if (!die_unsigned_constant_attribute(die, DW_AT_byte_size, byte_size))
    {
      if (!die_unsigned_constant_attribute(die, DW_AT_bit_size, bit_size))
    return false;
    }
  else
    bit_size = byte_size * 8;
 
  size = bit_size;
 
  return true;
}
 
/// Get the access specifier (from the DW_AT_accessibility attribute
/// value) of a given DIE.
///
/// @param die the DIE to consider.
///
/// @param access the resulting access.  This is set iff the function
/// returns true.
///
/// @return bool if the DIE contains the DW_AT_accessibility die.
static bool
die_access_specifier(Dwarf_Die * die, access_specifier& access)
{
  if (!die)
    return false;
 
  uint64_t a = 0;
  if (!die_unsigned_constant_attribute(die, DW_AT_accessibility, a))
    return false;
 
  access_specifier result = private_access;
 
  switch (a)
    {
    case private_access:
      result = private_access;
      break;
 
    case protected_access:
      result = protected_access;
      break;
 
    case public_access:
      result = public_access;
      break;
 
    default:
      break;
    }
 
  access = result;
  return true;
}
 
/// Test whether a given DIE represents a decl that is public.  That
/// is, one with the DW_AT_external attribute set.
///
/// @param die the DIE to consider for testing.
///
/// @return true if a DW_AT_external attribute is present and its
/// value is set to the true; return false otherwise.
static bool
die_is_public_decl(const Dwarf_Die* die)
{
  if (!die)
    return false;
  bool is_public = false;
 
  // If this is a DW_TAG_subprogram DIE, look for the
  // DW_AT_external attribute on it.  Otherwise, if it's a non-anonymous namespace,
  // then it's public.  In all other cases, this should return false.
 
  int tag = dwarf_tag(const_cast<Dwarf_Die*>(die));
  if (tag == DW_TAG_subprogram || tag == DW_TAG_variable)
    die_flag_attribute(die, DW_AT_external, is_public);
  else if (tag == DW_TAG_namespace)
    {
      string name = die_name(die);
      is_public = !name.empty();
    }
 
  return is_public;
}
 
/// Test if a DIE is effectively public.
///
/// This is meant to return true when either the DIE is public or when
/// it's a variable DIE that is at (global) namespace level.
///
/// @return true iff either the DIE is public or is a variable DIE
/// that is at (global) namespace level.
static bool
die_is_effectively_public_decl(const reader& rdr,
                   const Dwarf_Die* die)
{
  if (die_is_public_decl(die))
    return true;
 
  unsigned tag = dwarf_tag(const_cast<Dwarf_Die*>(die));
  if (tag == DW_TAG_variable || tag == DW_TAG_member)
    {
      // The DIE is a variable.
      Dwarf_Die parent_die;
      size_t where_offset = 0;
      if (!get_parent_die(rdr, die, parent_die, where_offset))
    return false;
 
      tag = dwarf_tag(&parent_die);
      if (tag == DW_TAG_compile_unit
      || tag == DW_TAG_partial_unit
      || tag == DW_TAG_type_unit)
    // The DIE is at global scope.
    return true;
 
      if (tag == DW_TAG_namespace)
    {
      string name = die_name(&parent_die);
      if (name.empty())
        // The DIE at unnamed namespace scope, so it's not public.
        return false;
      // The DIE is at namespace scope.
      return true;
    }
    }
  return false;
}
 
/// Test whether a given DIE represents a declaration-only DIE.
///
/// That is, if the DIE has the DW_AT_declaration flag set.
///
/// @param die the DIE to consider.
//
/// @return true if a DW_AT_declaration is present, false otherwise.
static bool
die_is_declaration_only(Dwarf_Die* die)
{
  bool is_declaration = false;
  die_flag_attribute(die, DW_AT_declaration, is_declaration, false);
  if (is_declaration && !die_has_size_attribute(die))
    return true;
  return false;
}
 
/// Test if a DIE is for a function decl.
///
/// @param die the DIE to consider.
///
/// @return true iff @p die represents a function decl.
static bool
die_is_function_decl(const Dwarf_Die *die)
{
  if (!die)
    return false;
 
  int tag = dwarf_tag(const_cast<Dwarf_Die*>(die));
  if (tag == DW_TAG_subprogram)
    return true;
  return false;
}
 
/// Test if a DIE is for a variable decl.
///
/// @param die the DIE to consider.
///
/// @return true iff @p die represents a variable decl.
static bool
die_is_variable_decl(const Dwarf_Die *die)
{
    if (!die)
    return false;
 
  int tag = dwarf_tag(const_cast<Dwarf_Die*>(die));
  if (tag == DW_TAG_variable)
    return true;
  return false;
}
 
/// Test if a DIE has size attribute.
///
/// @param die the DIE to consider.
///
/// @return true if the DIE has a size attribute.
static bool
die_has_size_attribute(const Dwarf_Die *die)
{
  uint64_t s;
  if (die_size_in_bits(die, s))
    return true;
  return false;
}
 
/// Test that a DIE has no child DIE.
///
/// @param die the DIE to consider.
///
/// @return true iff @p die has no child DIE.
static bool
die_has_no_child(const Dwarf_Die *die)
{
  if (!die)
    return true;
 
  Dwarf_Die child;
  if (dwarf_child(const_cast<Dwarf_Die*>(die), &child) == 0)
    return false;
  return true;
}
 
/// Test whether a given DIE represents a declaration-only DIE.
///
/// That is, if the DIE has the DW_AT_declaration flag set.
///
/// @param die the DIE to consider.
//
/// @return true if a DW_AT_declaration is present, false otherwise.
static bool
die_is_declaration_only(const Dwarf_Die* die)
{return die_is_declaration_only(const_cast<Dwarf_Die*>(die));}
 
/// Tests whether a given DIE is artificial.
///
/// @param die the test to test for.
///
/// @return true if the DIE is artificial, false otherwise.
static bool
die_is_artificial(Dwarf_Die* die)
{
  bool is_artificial;
  return die_flag_attribute(die, DW_AT_artificial, is_artificial);
}
 
///@return true if a tag represents a type, false otherwise.
///
///@param tag the tag to consider.
static bool
is_type_tag(unsigned tag)
{
  bool result = false;
 
  switch (tag)
    {
    case DW_TAG_array_type:
    case DW_TAG_class_type:
    case DW_TAG_enumeration_type:
    case DW_TAG_pointer_type:
    case DW_TAG_reference_type:
    case DW_TAG_string_type:
    case DW_TAG_structure_type:
    case DW_TAG_subroutine_type:
    case DW_TAG_typedef:
    case DW_TAG_union_type:
    case DW_TAG_ptr_to_member_type:
    case DW_TAG_set_type:
    case DW_TAG_subrange_type:
    case DW_TAG_base_type:
    case DW_TAG_const_type:
    case DW_TAG_file_type:
    case DW_TAG_packed_type:
    case DW_TAG_thrown_type:
    case DW_TAG_volatile_type:
    case DW_TAG_restrict_type:
    case DW_TAG_interface_type:
    case DW_TAG_unspecified_type:
    case DW_TAG_shared_type:
    case DW_TAG_rvalue_reference_type:
    case DW_TAG_coarray_type:
    case DW_TAG_atomic_type:
    case DW_TAG_immutable_type:
      result = true;
      break;
 
    default:
      result = false;
      break;
    }
 
  return result;
}
 
/// Test if a given DIE is a type whose canonical type is to be
/// propagated during DIE canonicalization
///
/// This is a sub-routine of compare_dies.
///
/// @param tag the tag of the DIE to consider.
///
/// @return true iff the DIE of tag @p tag is can see its canonical
/// type be propagated during the type comparison that happens during
/// DIE canonicalization.
static bool
is_canon_type_to_be_propagated_tag(unsigned tag)
{
  bool result = false;
 
  switch (tag)
    {
    case DW_TAG_class_type:
    case DW_TAG_structure_type:
    case DW_TAG_union_type:
    case DW_TAG_subroutine_type:
    case DW_TAG_subprogram:
      result = true;
      break;
 
    default:
      result = false;
      break;
    }
 
  return result;
}
 
/// Test if a given kind of DIE ought to have its comparison result
/// cached by compare_dies, so that subsequent invocations of
/// compare_dies can be faster.
///
/// @param tag the tag of the DIE to consider.
///
/// @return true iff DIEs of the tag @p tag ought to have its
/// comparison results cached.
static bool
type_comparison_result_to_be_cached(unsigned tag)
{
  bool r = false;
  switch (tag)
    {
    case DW_TAG_class_type:
    case DW_TAG_structure_type:
    case DW_TAG_union_type:
    case DW_TAG_subroutine_type:
    case DW_TAG_subprogram:
      r = true;
      break;
 
    default:
      r = false;
      break;
    }
  return r;
}
 
/// Cache the result of comparing to type DIEs.
///
/// @param rdr the context to consider.
///
/// @param tag the tag of the DIEs to consider.
///
/// @param p the offsets of the pair of DIEs being compared.
///
/// @param result the comparison result to be cached.
static bool
maybe_cache_type_comparison_result(const reader& rdr,
                   int tag,
                   const offset_pair_type& p,
                   comparison_result result)
{
  if (!type_comparison_result_to_be_cached(tag)
      || (result != COMPARISON_RESULT_EQUAL
      && result != COMPARISON_RESULT_DIFFERENT))
    return false;
 
  rdr.die_comparison_results_[p] = result;
 
  return true;
 
}
 
/// Get the cached result of the comparison of a pair of DIEs.
///
/// @param rdr the context to consider.
///
/// @param tag the tag of the pair of DIEs to consider.
///
/// @param p the offsets of the pair of DIEs to consider.
///
/// @param result out parameter set to the cached result of the
/// comparison of @p p if it has been found.
///
/// @return true iff a cached result for the comparisonof @p has been
/// found and set into @p result.
static bool
get_cached_type_comparison_result(const