LLVM 20.0.0git
DWARFLinker.h
Go to the documentation of this file.
1//===- DWARFLinker.h --------------------------------------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8
9#ifndef LLVM_DWARFLINKER_PARALLEL_DWARFLINKER_H
10#define LLVM_DWARFLINKER_PARALLEL_DWARFLINKER_H
11
17#include "llvm/MC/MCDwarf.h"
19
20/// ------------------------------------------------------------------
21/// The core of the Dwarf linking logic.
22///
23/// The generation of the dwarf information from the object files will be
24/// driven by the selection of 'root DIEs', which are DIEs that
25/// describe variables or functions that resolves to the corresponding
26/// code section(and thus have entries in the Addresses map). All the debug
27/// information that will be generated(the DIEs, but also the line
28/// tables, ranges, ...) is derived from that set of root DIEs.
29///
30/// The root DIEs are identified because they contain relocations that
31/// points to code section(the low_pc for a function, the location for
32/// a variable). These relocations are gathered as a very first step
33/// when we start processing a object file by AddressesMap.
34///
35/// The overall linking process looks like this:
36///
37/// parrallel_for_each(ObjectFile) {
38/// for_each (Compile Unit) {
39/// 1. Load Clang modules.
40/// }
41///
42/// parrallel_for_each(Compile Unit) {
43/// 1. Load input DWARF for Compile Unit.
44/// 2. Report warnings for Clang modules.
45/// 3. Analyze live DIEs and type names(if ODR deduplication is requested).
46/// 4. Clone DIEs(Generate output DIEs and resulting DWARF tables).
47/// The result is in an OutDebugInfoBytes, which is an ELF file
48/// containing DWARF tables corresponding to the current compile unit.
49/// 5. Cleanup Input and Output DIEs.
50/// }
51///
52/// Deallocate loaded Object file.
53/// }
54///
55/// if (ODR deduplication is requested)
56/// Generate an artificial compilation unit ("Type Table": used to partially
57/// generate DIEs at the clone stage).
58///
59/// for_each (ObjectFile) {
60/// for_each (Compile Unit) {
61/// 1. Set offsets to Compile Units DWARF tables.
62/// 2. Sort offsets/attributes/patches to have a predictable result.
63/// 3. Patch size/offsets fields.
64/// 4. Generate index tables.
65/// 5. Move DWARF tables of compile units into the resulting file.
66/// }
67/// }
68///
69/// Every compile unit is processed separately, visited only once
70/// (except case inter-CU references exist), and used data is freed
71/// after the compile unit is processed. The resulting file is glued together
72/// from the generated debug tables which correspond to separate compile units.
73///
74/// Handling inter-CU references: inter-CU references are hard to process
75/// using only one pass. f.e. if CU1 references CU100 and CU100 references
76/// CU1, we could not finish handling of CU1 until we finished CU100.
77/// Thus we either need to load all CUs into the memory, either load CUs several
78/// times. This implementation loads inter-connected CU into memory at the first
79/// pass and processes them at the second pass.
80///
81/// ODR deduplication: Artificial compilation unit will be constructed to keep
82/// type dies. All types are moved into that compilation unit. Type's references
83/// are patched so that they point to the corresponding types from artificial
84/// compilation unit. All partial type definitions would be merged into single
85/// type definition.
86///
87
88namespace llvm {
89namespace dwarf_linker {
90namespace parallel {
91
92/// This structure keeps data of the concrete section.
97 virtual ~SectionDescriptorBase() = default;
98 /// Returns section content.
99 virtual StringRef getContents() = 0;
100 /// Returns section kind.
102 /// Returns section name.
104 /// Returns endianess used by section.
106 /// Returns FormParams used by section.
108
109protected:
110 /// The section kind.
112 /// Output format.
115};
116
118 std::function<void(std::shared_ptr<SectionDescriptorBase> Section)>;
119
121public:
122 virtual ~DWARFLinker() = default;
123
124 /// Creates dwarf linker instance.
125 static std::unique_ptr<DWARFLinker>
127
128 /// Set output DWARF handler. Result of linking DWARF is set of sections
129 /// containing final debug info. DWARFLinkerBase::link() pass generated
130 /// sections using specified \p SectionHandler.
131 virtual void setOutputDWARFHandler(const Triple &TargetTriple,
132 SectionHandlerTy SectionHandler) = 0;
133};
134
135} // end of namespace parallel
136} // end of namespace dwarf_linker
137} // end of namespace llvm
138
139#endif // LLVM_DWARFLINKER_PARALLEL_DWARFLINKER_H
static fatal_error_handler_t ErrorHandler
SectionKind - This is a simple POD value that classifies the properties of a section.
Definition: SectionKind.h:22
A wrapper around a string literal that serves as a proxy for constructing global tables of StringRefs...
Definition: StringRef.h:838
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
Triple - Helper class for working with autoconf configuration names.
Definition: Triple.h:44
The base interface for DWARFLinker implementations.
std::function< void(const Twine &Warning, StringRef Context, const DWARFDie *DIE)> MessageHandlerTy
virtual void setOutputDWARFHandler(const Triple &TargetTriple, SectionHandlerTy SectionHandler)=0
Set output DWARF handler.
static std::unique_ptr< DWARFLinker > createLinker(MessageHandlerTy ErrorHandler, MessageHandlerTy WarningHandler)
Creates dwarf linker instance.
Definition: DWARFLinker.cpp:17
std::function< void(std::shared_ptr< SectionDescriptorBase > Section)> SectionHandlerTy
Definition: DWARFLinker.h:118
static constexpr const StringLiteral & getSectionName(DebugSectionKind SectionKind)
Return the name of the section.
DebugSectionKind
List of tracked debug tables.
@ DWARF32
Definition: Dwarf.h:91
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
endianness
Definition: bit.h:70
A helper struct providing information about the byte size of DW_FORM values that vary in size dependi...
Definition: Dwarf.h:1077
This structure keeps data of the concrete section.
Definition: DWARFLinker.h:93
llvm::endianness getEndianess() const
Returns endianess used by section.
Definition: DWARFLinker.h:105
DebugSectionKind SectionKind
The section kind.
Definition: DWARFLinker.h:111
dwarf::FormParams getFormParams() const
Returns FormParams used by section.
Definition: DWARFLinker.h:107
DebugSectionKind getKind()
Returns section kind.
Definition: DWARFLinker.h:101
SectionDescriptorBase(DebugSectionKind SectionKind, dwarf::FormParams Format, llvm::endianness Endianess)
Definition: DWARFLinker.h:94
virtual StringRef getContents()=0
Returns section content.
const StringLiteral & getName() const
Returns section name.
Definition: DWARFLinker.h:103