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