DWARF: Provide accessors to DIERef fields

[labath]

Summary

Instead of accessing the fields directly, use accessor functions to
provide access to the DIERef components. This allows us to decouple the
external interface, from the internal representation. The external
interface can use llvm::Optional and similar goodies, while the data can
still be stored internally in a more compact representation.

I also document the purpose of the existing DIERef fields.

The main motivation for this change is a need to introduce an additional
field to the DIERef class, but I believe the change has its own merit.

[labath]

(also, cu_offset is renamed to unit_offset, as we now support type units too)

[labath]

• s/DW_INVALID_OFFSET/llvm::None/ in HashedNameToDIE.h

[clayborg]

Just questioning if we want to increase the size of the DIERef struct.

source/Plugins/SymbolFile/DWARF/DIERef.h

47–48

We we want this to be:

dw_offset_t m_section:1;
dw_offset_t m_unit_offset:31;

Otherwise we increase the size of the DIERef struct?

[clayborg]

source/Plugins/SymbolFile/DWARF/DIERef.h

48

Never mind, saw your other DWO related patch. Makes sense now.

source/Plugins/SymbolFile/DWARF/AppleDWARFIndex.cpp

if (m_apple_names_up->AppendAllDIEsThatMatchingRegex(regex, hash_data))
     DWARFMappedHash::ExtractDIEArray(hash_data, offsets);
 }
 
 void AppleDWARFIndex::ReportInvalidDIERef(const DIERef &ref,
                                           llvm::StringRef name) {
   m_module.ReportErrorIfModifyDetected(
       "the DWARF debug information has been modified (accelerator table had "
       "bad die 0x%8.8x for '%s')\n",
-      ref.die_offset, name.str().c_str());
+      ref.die_offset(), name.str().c_str());
 }
 
 void AppleDWARFIndex::Dump(Stream &s) {
   if (m_apple_names_up)
     s.PutCString(".apple_names index present\n");
   if (m_apple_namespaces_up)
     s.PutCString(".apple_namespaces index present\n");
   if (m_apple_types_up)
     s.PutCString(".apple_types index present\n");
   if (m_apple_objc_up)
     s.PutCString(".apple_objc index present\n");
   // TODO: Dump index contents
 }

source/Plugins/SymbolFile/DWARF/DIERef.h

 //===-- DIERef.h ------------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef SymbolFileDWARF_DIERef_h_
 #define SymbolFileDWARF_DIERef_h_
 
 #include "lldb/Core/dwarf.h"
+#include "llvm/ADT/Optional.h"
+#include "llvm/Support/FormatProviders.h"
 #include <vector>
 
-struct DIERef {
+/// Identifies a DWARF debug info entry within a given Module. It contains three
+/// "coordinates":
+/// - section: identifies the section of the debug info entry: debug_info or
+///   debug_types
+/// - unit_offset: the offset of the unit containing the debug info entry. For
+///   regular (unsplit) units, this field is optional, as the die_offset is
+///   enough to uniquely identify the containing unit. For split units, this
+///   field must contain the offset of the skeleton unit in the main object
+///   file.
+/// - die_offset: The offset of te debug info entry as an absolute offset from
+///   the beginning of the section specified in the section field.
+class DIERef {
+public:
   enum Section : uint8_t { DebugInfo, DebugTypes };
 
-  DIERef(Section s, dw_offset_t c, dw_offset_t d)
-      : section(s), cu_offset(c), die_offset(d) {}
-
-  Section section;
-  dw_offset_t cu_offset;
-  dw_offset_t die_offset;
+  DIERef(Section s, llvm::Optional<dw_offset_t> u, dw_offset_t d)
+      : m_section(s), m_unit_offset(u.getValueOr(DW_INVALID_OFFSET)),
+        m_die_offset(d) {}
+
+  Section section() const { return static_cast<Section>(m_section); }
+
+  llvm::Optional<dw_offset_t> unit_offset() const {
+    if (m_unit_offset != DW_INVALID_OFFSET)
+      return m_unit_offset;
+    return llvm::None;
+  }
+
+  dw_offset_t die_offset() const { return m_die_offset; }
+
+private:
+  unsigned m_section : 1;
+  dw_offset_t m_unit_offset;
+  dw_offset_t m_die_offset;
 };
 
 typedef std::vector<DIERef> DIEArray;
 
+namespace llvm {
+template<> struct format_provider<DIERef> {
+  static void format(const DIERef &ref, raw_ostream &OS, StringRef Style);
+};
+} // namespace llvm
+
 #endif // SymbolFileDWARF_DIERef_h_

source/Plugins/SymbolFile/DWARF/DIERef.cpp

 //===-- DIERef.cpp ----------------------------------------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #include "DIERef.h"
+#include "llvm/Support/Format.h"
+
+void llvm::format_provider<DIERef>::format(const DIERef &ref, raw_ostream &OS,
+                                           StringRef Style) {
+  OS << (ref.section() == DIERef::DebugInfo ? "INFO" : "TYPE");
+  if (ref.unit_offset())
+    OS << "/" << format_hex_no_prefix(*ref.unit_offset(), 8);
+  OS << "/" << format_hex_no_prefix(ref.die_offset(), 8);
+}

source/Plugins/SymbolFile/DWARF/DWARFDebugInfo.cpp

if (result && result->GetOffset() != cu_offset) {
     idx = DW_INVALID_INDEX;
   }
   if (idx_ptr)
     *idx_ptr = idx;
   return result;
 }
 
 DWARFUnit *DWARFDebugInfo::GetUnit(const DIERef &die_ref) {
-  if (die_ref.cu_offset == DW_INVALID_OFFSET)
-    return GetUnitContainingDIEOffset(die_ref.section, die_ref.die_offset);
-  else
-    return GetUnitAtOffset(die_ref.section, die_ref.cu_offset);
+  if (die_ref.unit_offset())
+    return GetUnitAtOffset(die_ref.section(), *die_ref.unit_offset());
+  return GetUnitContainingDIEOffset(die_ref.section(), die_ref.die_offset());
 }
 
 DWARFUnit *
 DWARFDebugInfo::GetUnitContainingDIEOffset(DIERef::Section section,
                                            dw_offset_t die_offset) {
   uint32_t idx = FindUnitIndex(section, die_offset);
   DWARFUnit *result = GetUnitAtIndex(idx);
   if (result && !result->ContainsDIEOffset(die_offset))

 
 // GetDIE()
 //
 // Get the DIE (Debug Information Entry) with the specified offset.
 DWARFDIE
 DWARFDebugInfo::GetDIE(const DIERef &die_ref) {
   DWARFUnit *cu = GetUnit(die_ref);
   if (cu)
-    return cu->GetDIE(die_ref.die_offset);
+    return cu->GetDIE(die_ref.die_offset());
   return DWARFDIE(); // Not found
 }
 

source/Plugins/SymbolFile/DWARF/DebugNamesDWARFIndex.cpp

if (entry.tag() != DW_TAG_structure_type &&
         entry.tag() != DW_TAG_class_type)
       continue;
 
     llvm::Optional<DIERef> ref = ToDIERef(entry);
     if (!ref)
       continue;
 
     DWARFUnit *cu = m_debug_info.GetUnitAtOffset(DIERef::Section::DebugInfo,
-                                                 ref->cu_offset);
+                                                 *ref->unit_offset());
     if (!cu || !cu->Supports_DW_AT_APPLE_objc_complete_type()) {
       incomplete_types.push_back(*ref);
       continue;
     }
 
     // FIXME: We should return DWARFDIEs so we don't have to resolve it twice.
     DWARFDIE die = m_debug_info.GetDIE(*ref);
     if (!die)

source/Plugins/SymbolFile/DWARF/NameToDIE.cpp

 using namespace lldb_private;
 
 void NameToDIE::Finalize() {
   m_map.Sort();
   m_map.SizeToFit();
 }
 
 void NameToDIE::Insert(ConstString name, const DIERef &die_ref) {
+  assert(die_ref.unit_offset().hasValue());
   m_map.Append(name, die_ref);
 }
 
 size_t NameToDIE::Find(ConstString name, DIEArray &info_array) const {
   return m_map.GetValues(name, info_array);
 }
 
 size_t NameToDIE::Find(const RegularExpression &regex,
                        DIEArray &info_array) const {
   return m_map.GetValues(regex, info_array);
 }
 
 size_t NameToDIE::FindAllEntriesForCompileUnit(dw_offset_t cu_offset,
                                                DIEArray &info_array) const {
   const size_t initial_size = info_array.size();
   const uint32_t size = m_map.GetSize();
   for (uint32_t i = 0; i < size; ++i) {
     const DIERef &die_ref = m_map.GetValueAtIndexUnchecked(i);
-    if (cu_offset == die_ref.cu_offset)
+    if (cu_offset == *die_ref.unit_offset())
       info_array.push_back(die_ref);
   }
   return info_array.size() - initial_size;
 }
 
 void NameToDIE::Dump(Stream *s) {
   const uint32_t size = m_map.GetSize();
   for (uint32_t i = 0; i < size; ++i) {
-    ConstString cstr = m_map.GetCStringAtIndex(i);
-    const DIERef &die_ref = m_map.GetValueAtIndexUnchecked(i);
-    s->Printf("%p: {0x%8.8x/0x%8.8x} \"%s\"\n", (const void *)cstr.GetCString(),
-              die_ref.cu_offset, die_ref.die_offset, cstr.GetCString());
+    s->Format("{0} \"{1}\"\n", m_map.GetValueAtIndexUnchecked(i),
+              m_map.GetCStringAtIndexUnchecked(i));
   }
 }
 
 void NameToDIE::ForEach(
     std::function<bool(ConstString name, const DIERef &die_ref)> const
         &callback) const {
   const uint32_t size = m_map.GetSize();
   for (uint32_t i = 0; i < size; ++i) {

source/Plugins/SymbolFile/DWARF/SymbolFileDWARF.h

lldb::user_id_t GetUID(const DWARFBaseDIE &die) {
     return LLDB_INVALID_UID;
   }
 
   lldb::user_id_t GetUID(const llvm::Optional<DIERef> &ref) {
     return ref ? GetUID(*ref) : LLDB_INVALID_UID;
   }
 
   lldb::user_id_t GetUID(const DIERef &ref) {
-    return GetID() | ref.die_offset |
-           (lldb::user_id_t(ref.section == DIERef::Section::DebugTypes) << 63);
+    return GetID() | ref.die_offset() |
+           (lldb::user_id_t(ref.section() == DIERef::Section::DebugTypes)
+            << 63);
   }
 
   virtual std::unique_ptr<SymbolFileDWARFDwo>
   GetDwoSymbolFileForCompileUnit(DWARFUnit &dwarf_cu,
                                  const DWARFDebugInfoEntry &cu_die);
 
   // For regular SymbolFileDWARF instances the method returns nullptr,
   // for the instances of the subclass SymbolFileDWARFDwo

source/Plugins/SymbolFile/DWARF/SymbolFileDWARFDwo.cpp

 
 TypeSystem *
 SymbolFileDWARFDwo::GetTypeSystemForLanguage(LanguageType language) {
   return GetBaseSymbolFile().GetTypeSystemForLanguage(language);
 }
 
 DWARFDIE
 SymbolFileDWARFDwo::GetDIE(const DIERef &die_ref) {
-  lldbassert(die_ref.cu_offset == m_base_dwarf_cu.GetOffset() ||
-             die_ref.cu_offset == DW_INVALID_OFFSET);
-  return DebugInfo()->GetDIEForDIEOffset(die_ref.section, die_ref.die_offset);
+  lldbassert(!die_ref.unit_offset() ||
+             *die_ref.unit_offset() == m_base_dwarf_cu.GetOffset());
+  return DebugInfo()->GetDIEForDIEOffset(die_ref.section(),
+                                         die_ref.die_offset());
 }