[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
1 \chapter[Split DWARF Objects (Informative)]{Split DWARF Objects (Informative)}
2 \label{app:splitdwarfobjectsinformative}
4 With the traditional DWARF format, debug information is designed
5 with the expectation that it will be processed by the linker to
6 produce an output binary with complete debug information, and
7 with fully-resolved references to locations within the
8 application. For very large applications, however, this approach
9 can result in excessively large link times and excessively large
10 output files. 
12 Several vendors have independently developed
13 proprietary approaches that allow the debug information to remain
14 in the relocatable object files, so that the linker does not have
15 to process the debug information or copy it to the output file.
16 These approaches have all required that additional information be
17 made available to the debug information consumer, and that the
18 consumer perform some minimal amount of relocation in order to
19 interpret the debug info correctly. The additional information
20 required, in the form of load maps or symbol tables, and the
21 details of the relocation are not covered by the DWARF
22 specification, and vary with each vendor's implementation.
24 These limitations are removed by the design described here.
26 \section{Overview}
27 \label{app:splitoverview}
28 \DWARFVersionV{} introduces an optional set of debugging sections
29 that allow the compiler to partition the debugging information
30 into a set of (small) sections that require link-time relocation
31 and a set of (large) sections that do not. The sections that
32 require relocation are written to the relocatable object file as
33 usual, and are linked into the final executable. The sections
34 that do not require relocation, however, can be written to the
35 relocatable object (.o) file but ignored by the linker, or they
36 can be written to a separate DWARF object (dwo{}) file.
38 \needlines{4}
39 The optional set of debugging sections includes the following:
40 \begin{itemize}
41 \item
42 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
43 \DWTAGtypeunit{} DIEs and
44 their descendants. This is the bulk of the debugging
45 information for the compilation unit that is normally found
46 in the \dotdebuginfo{} section.
47 \item
48 \dotdebugabbrevdwo{} - Contains the abbreviations tables used by
49 the \dotdebuginfodwo{} sections.
50 \item
51 \dotdebuglocdwo{} - Contains the location lists referenced by
52 the debugging information entries in the \dotdebuginfodwo{}
53 section. This contains the location lists normally found in 
54 the \dotdebugloc{} section,
55 with a slightly modified format to eliminate the need for
56 relocations.
57 \item
58 \dotdebugstrdwo{} - Contains the string table for all indirect
59 strings referenced by the debugging information in the
60 \dotdebuginfodwo{} sections.
61 \item
62 \dotdebugstroffsetsdwo{} - Contains the string offsets table
63 for the strings in the \dotdebugstrdwo{}{} section.
64 \item
65 \dotdebugmacrodwo{} - Contains macro definition information,
66 normally found in the \dotdebugmacro{} section.
67 \item
68 \dotdebuglinedwo{} - Contains skeleton line tables for the type
69 units in the \dotdebuginfodwo{} section. These line tables
70 contain only the directory and files lists needed to
71 interpret \DWATdeclfile{} attributes in the debugging
72 information entries. Actual line number tables remain in the
73 \dotdebugline{} section, and remain in the relocatable object
74 (.o) files.
75 \end{itemize}
77 In order for the consumer to locate and process the debug
78 information, the compiler must produce a small amount of debug
79 information that passes through the linker into the output
80 binary. A skeleton \dotdebuginfo{} section for each compilation unit
81 contains a reference to the corresponding ".o" or ".dwo"
82 file, and the \dotdebugline{} section (which is typically small
83 compared to the \dotdebuginfo{} sections) is
84 linked into the output binary, as is the new \dotdebugaddr{}
85 section.
87 \needlines{6}
88 The debug sections that continue to be linked into the
89 output binary include the following:
90 \begin{itemize}
91 \item
92 \dotdebugabbrev{} - Contains the abbreviation codes used by the
93 skeleton \dotdebuginfo{} section.
94 \item
95 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
96 but no children.
97 \item
98 \dotdebugstr{} - Contains any strings referenced by the skeleton
99 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
100 \item
101 \dotdebugstroffsets{} - Contains the string offsets table for
102 the strings in the \dotdebugstr{} section.
103 \item
104 \dotdebugaddr{} - Contains references to loadable sections,
105 indexed by attributes of form \DWFORMaddrx{} or location
106 expression \DWOPaddrx{} opcodes.
107 \item
108 \dotdebugline{} - Contains the line number tables, unaffected by
109 this design. (These could be moved to the .dwo file, but in
110 order to do so, each \DWLNEsetaddress{} opcode would need to
111 be replaced by a new opcode that referenced an entry in the
112 \dotdebugaddr{} section. Furthermore, leaving this section in the
113 .o file allows many debug info consumers to remain unaware of
114 .dwo files.)
115 \item
116 \dotdebugframe{} - Contains the frame tables, unaffected by this
117 design.
118 \item
119 \dotdebugranges{} - Contains the range lists, unaffected by this
120 design.
121 \item
122 \dotdebugpubnames{} - Contains the public names for use in
123 building an index section. This section has the same
124 format and use as always. The section header refers to a
125 compilation unit offset, which is the offset of the
126 skeleton compilation unit in the \dotdebuginfo{} section.
127 \item
128 \dotdebugpubtypes{} - Contains the public types for use in
129 building an index section. This section has the same
130 format and use as always. The section header refers to a
131 compilation unit offset, which is the offset of the
132 skeleton compilation unit in the \dotdebuginfo{} section.
133 \item
134 \dotdebugaranges{} - Contains the accelerated range lookup table
135 for the compilation unit, unaffected by this design.
136 \end{itemize}
138 \needlines{6}
139 The skeleton \DWTAGcompileunit{} DIE has the following attributes:
140 \autocols[0pt]{c}{3}{l}{
141 \DWATaddrbase{},
142 \DWATcompdir{},
143 \DWATdwoname{},
144 \DWATdwoid{},
145 \DWAThighpc{} \dag,
146 \DWATlowpc{} \dag,
147 \DWATranges{} \dag,
148 \DWATrangesbase{},
149 \DWATstmtlist{},
150 \DWATstroffsetsbase{}
151 }
152 \dag{} If \DWATranges{} is present, \DWATlowpc{} and \DWAThighpc{} are
153 not used, and vice versa.
155 All other attributes of the compilation unit DIE are moved to
156 the full DIE in the \dotdebuginfodwo{} section.
158 Because of other improvements in \DWARFVersionV, most of the
159 relocations that would normally be found in the \dotdebuginfodwo{}
160 sections are moved to the \dotdebugaddr{} and
161 \dotdebugstroffsetsdwo{} sections. Those in the
162 \dotdebugstroffsetsdwo{} sections are simply omitted because the
163 DWARF information in those sections is not combined at link
164 time, so no relocation is necessary. Similarly,
165 many of the remaining relocations referring to range lists are
166 eliminated. 
168 The relocations that remain fall into the following categories:
169 \begin{itemize}
170 \item
171 References from compilation unit and type unit headers to the
172 \dotdebugabbrevdwo{} section. Because the new sections are not
173 combined at link time, these references need no relocations.
174 \item
175 References from \DWTAGcompileunit{} DIEs to the
176 \dotdebuglinedwo{} section, via \DWATstmtlist{}. This attribute
177 remains in the skeleton \dotdebuginfo{} section, so no
178 relocation in the \dotdebuginfodwo{} section is necessary.
179 \item
180 References from \DWTAGtypeunit{} DIEs to the skeleton
181 \dotdebuglinedwo{} section, via \DWATstmtlist{}. Because the new
182 sections are not combined at link time, these references need
183 no relocations.
184 \item
185 References from \DWTAGcompileunit{} and \DWTAGtypeunit{} DIEs
186 to the \dotdebugstroffsetsdwo{} section, via
187 \DWATstroffsetsbase{}. Because the new sections are not
188 combined at link time, the \DWATstroffsetsbase{} attribute
189 is not required in a \dotdebuginfodwo{}
190 section.
191 \item
192 References from \DWTAGcompileunit{} DIEs to the \dotdebugaddr{}
193 section, via \DWATaddrbase{}. This attribute remains in
194 the skeleton \dotdebuginfo{} section, so no relocation in the
195 \dotdebuginfodwo{} section is necessary.
196 \needlines{4}
197 \item
198 References from \DWTAGcompileunit{} DIEs to the \dotdebugranges{}
199 section, via \DWATrangesbase{}. This attribute remains in
200 the skeleton \dotdebuginfo{} section, so no relocation in the
201 \dotdebuginfodwo{} section is necessary.
202 \item
203 References from the \dotdebuglocdwo{} section to machine addresses
204 via a location list entry or a base address selection entry.
205 With a minor change to the location list entry format,
206 described below, these relocations are also eliminated.
207 \end{itemize}
209 Each location list entry contains beginning and ending address
210 offsets, which normally may be relocated addresses. In the
211 \dotdebuglocdwo{} section, these offsets are replaced by indices
212 into the \dotdebugaddr{} section. Each location list entry begins
213 with a single byte identifying the entry type:
214 \begin{itemize}
215 \item
216 \DWLLEendoflistentry{} (0) indicates an end-of-list entry,
217 \item
218 \DWLLEbaseaddressselectionentry{} (1) indicates a base address
219 selection entry, 
220 \item
221 \DWLLEstartendentry{} (2) indicates a normal
222 location list entry providing start and end addresses,
223 \item
224 \DWLLEstartlengthentry{} (3) indicates a normal location list
225 entry providing a start address and a length, and
226 \item
227 \DWLLEoffsetpairentry{} (4) indicates a normal location list
228 entry providing start and end offsets relative to the base
229 address. 
230 \end{itemize}
231 An end-of-list entry has no further data. A base address
232 selection entry contains a single unsigned LEB128 number
233 following the entry type byte, which is an index into the
234 \dotdebugaddr{} section that selects the new base address for
235 subsequent location list entries. A start/end entry contains two
236 unsigned LEB128 numbers following the entry type byte, which are
237 indices into the \dotdebugaddr{} section that select the beginning
238 and ending addresses. A start/length entry contains one unsigned
239 LEB128 number and a 4-byte unsigned value (as would be
240 represented by the form code \DWFORMdatafour). The first number
241 is an index into the \dotdebugaddr{} section that selects the
242 beginning offset, and the second number is the length of the
243 range. Addresses fetched from the \dotdebugaddr{} section are not
244 relative to the base address. An offset pair entry contains two
245 4-byte unsigned values (as would be represented by the form code
246 \DWFORMdatafour){}, treated as the beginning and ending offsets,
247 respectively, relative to the base address. As in the \dotdebugloc{}
248 section, the base address is obtained either from the nearest
249 preceding base address selection entry, or, if there is no such
250 entry, from the compilation unit base address (as defined in
251 Section 3.1.1). For the latter three types (start/end,
252 start/length, and offset pair), the two operand values are
253 followed by a location description as in a normal location list
254 entry in the \dotdebugloc{} section.
256 This design depends on having an index of debugging information
257 available to the consumer. For name lookups, the consumer can use
258 the \dotdebugpubnames{} and \dotdebugpubtypes{} sections (or an index
259 built at link time based on the information in those sections),
260 which will lead to a skeleton compilation unit. The
261 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
262 compilation unit can then be used to locate the corresponding
263 DWARF object file for the compilation unit. Similarly, for an
264 address lookup, the consumer can use the \dotdebugaranges{} table,
265 which will also lead to a skeleton compilation unit. For a file
266 and line number lookup, the skeleton compilation units can be
267 used to locate the line number tables.
269 \section{Split DWARF Object Examples}
270 \label{app:splitdwarfobjectexamples}
272 TBD