Files for 2013-12-18 draft document. This incorporates
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
1 \chapter[Split DWARF Objects (Informative)]{Split DWARF Objects (Informative)}
2 \label{app:splitdwarfobjectsinformative}
3
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. 
11
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.
23
24 These limitations are removed by the design described here.
25
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.
37
38 \needlines{4}
39 The optional set of debugging sections includes the following:
40 \begin{itemize}
41 \item
42 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} DIE and
43 its descendants. This is the bulk of the debugging
44 information for the compilation unit that is normally found
45 in the \dotdebuginfo{} section.
46 \item
47 \dotdebugtypesdwo{} - Contains the \DWTAGtypeunit{} DIEs and
48 their descendants. This is the bulk of the debugging
49 information for the type units that is normally found in the
50 \dotdebugtypes{} section.
51 \item
52 \dotdebugabbrevdwo{} - Contains the abbreviations tables used by
53 the \dotdebuginfodwo{} and \dotdebugtypesdwo{} sections.
54 \item
55 \dotdebuglocdwo{} - Contains the location lists referenced by
56 the debugging information entries in the \dotdebuginfodwo{}
57 section. This contains the location lists normally found in 
58 the \dotdebugloc{} section,
59 with a slightly modified format to eliminate the need for
60 relocations.
61 \item
62 \dotdebugstrdwo{} - Contains the string table for all indirect
63 strings referenced by the debugging information in the
64 \dotdebuginfodwo{} and \dotdebugtypesdwo{} sections.
65 \item
66 \dotdebugstroffsetsdwo{} - Contains the string offsets table
67 for the strings in the \dotdebugstrdwo{}{} section.
68 \item
69 \dotdebugmacinfodwo{} - Contains macro definition information,
70 normally found in the \dotdebugmacinfo{} section.
71 \item
72 \dotdebuglinedwo{} - Contains skeleton line tables for the type
73 units in the \dotdebugtypesdwo{} section. These line tables
74 contain only the directory and files lists needed to
75 interpret \DWATdeclfile{} attributes in the debugging
76 information entries. Actual line number tables remain in the
77 \dotdebugline{} section, and remain in the relocatable object
78 (.o) files.
79 \end{itemize}
80
81 In order for the consumer to locate and process the debug
82 information, the compiler must produce a small amount of debug
83 information that passes through the linker into the output
84 binary. A skeleton \dotdebuginfo{} section for each compilation unit
85 contains a reference to the corresponding ".o" or ".dwo"
86 file, and the \dotdebugline{} section (which is typically small
87 compared to the \dotdebuginfo{} and \dotdebugtypes{} sections) is
88 linked into the output binary, as is the new \dotdebugaddr{}
89 section.
90
91 \needlines{6}
92 The debug sections that continue to be linked into the
93 output binary include the following:
94 \begin{itemize}
95 \item
96 \dotdebugabbrev{} - Contains the abbreviation codes used by the
97 skeleton \dotdebuginfo{} section.
98 \item
99 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
100 but no children.
101 \item
102 \dotdebugstr{} - Contains any strings referenced by the skeleton
103 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
104 \item
105 \dotdebugstroffsets{} - Contains the string offsets table for
106 the strings in the \dotdebugstr{} section.
107 \item
108 \dotdebugaddr{} - Contains references to loadable sections,
109 indexed by attributes of form \DWFORMaddrx{} or location
110 expression \DWOPaddrx{} opcodes.
111 \item
112 \dotdebugline{} - Contains the line number tables, unaffected by
113 this design. (These could be moved to the .dwo file, but in
114 order to do so, each \DWLNEsetaddress{} opcode would need to
115 be replaced by a new opcode that referenced an entry in the
116 \dotdebugaddr{} section. Furthermore, leaving this section in the
117 .o file allows many debug info consumers to remain unaware of
118 .dwo files.)
119 \item
120 \dotdebugframe{} - Contains the frame tables, unaffected by this
121 design.
122 \item
123 \dotdebugranges{} - Contains the range lists, unaffected by this
124 design.
125 \item
126 \dotdebugpubnames{} - Contains the public names for use in
127 building an index section. This section has the same
128 format and use as always. The section header refers to a
129 compilation unit offset, which is the offset of the
130 skeleton compilation unit in the \dotdebuginfo{} section.
131 \item
132 \dotdebugpubtypes{} - Contains the public types for use in
133 building an index section. This section has the same
134 format and use as always. The section header refers to a
135 compilation unit offset, which is the offset of the
136 skeleton compilation unit in the \dotdebuginfo{} section.
137 \item
138 \dotdebugaranges{} - Contains the accelerated range lookup table
139 for the compilation unit, unaffected by this design.
140 \end{itemize}
141
142 \needlines{6}
143 The skeleton \DWTAGcompileunit{} DIE has the following attributes:
144 \autocols[0pt]{c}{3}{l}{
145 \DWATaddrbase{},
146 \DWATcompdir{},
147 \DWATdwoname{},
148 \DWATdwoid{},
149 \DWAThighpc{} \dag,
150 \DWATlowpc{} \dag,
151 \DWATranges{} \dag,
152 \DWATrangesbase{},
153 \DWATstmtlist{},
154 \DWATstroffsetsbase{}
155 }
156 \dag{} If \DWATranges{} is present, \DWATlowpc{} and \DWAThighpc{} are
157 not used, and vice versa.
158
159 All other attributes of the compilation unit DIE are moved to
160 the full DIE in the \dotdebuginfodwo{} section.
161
162 Because of other improvements in \DWARFVersionV, most of the
163 relocations that would normally be found in the \dotdebuginfodwo{}
164 and \dotdebugtypesdwo{} sections is moved to the \dotdebugaddr{} and
165 \dotdebugstroffsetsdwo{} sections. Those in the
166 \dotdebugstroffsetsdwo{} sections are simply be omitted because the
167 DWARF information in those sections is not combined at link
168 time, so no relocation is necessary. Similarly,
169 many of the remaining relocations referring to range lists are
170 eliminated. 
171
172 The relocations that remain fall into the following categories:
173 \begin{itemize}
174 \item
175 References from compilation unit and type unit headers to the
176 \dotdebugabbrevdwo{} section. Because the new sections are not
177 combined at link time, these references need no relocations.
178 \item
179 References from \DWTAGcompileunit{} DIEs to the
180 \dotdebuglinedwo{} section, via \DWATstmtlist{}. This attribute
181 remains in the skeleton \dotdebuginfo{} section, so no
182 relocation in the \dotdebuginfodwo{} section is necessary.
183 \item
184 References from \DWTAGtypeunit{} DIEs to the skeleton
185 \dotdebuglinedwo{} section, via \DWATstmtlist{}. Because the new
186 sections are not combined at link time, these references need
187 no relocations.
188 \item
189 References from \DWTAGcompileunit{} and \DWTAGtypeunit{} DIEs
190 to the \dotdebugstroffsetsdwo{} section, via
191 \DWATstroffsetsbase{}. Because the new sections are not
192 combined at link time, the \DWATstroffsetsbase{} attribute
193 is not required in a \dotdebuginfodwo{} or \dotdebugtypesdwo{}
194 section.
195 \item
196 References from \DWTAGcompileunit{} DIEs to the \dotdebugaddr{}
197 section, via \DWATaddrbase{}. This attribute remains in
198 the skeleton \dotdebuginfo{} section, so no relocation in the
199 \dotdebuginfodwo{} section is necessary.
200 \needlines{4}
201 \item
202 References from \DWTAGcompileunit{} DIEs to the \dotdebugranges{}
203 section, via \DWATrangesbase{}. This attribute remains in
204 the skeleton \dotdebuginfo{} section, so no relocation in the
205 \dotdebuginfodwo{} section is necessary.
206 \item
207 References from the \dotdebuglocdwo{} section to machine addresses
208 via a location list entry or a base address selection entry.
209 With a minor change to the location list entry format,
210 described below, these relocations are also eliminated.
211 \end{itemize}
212
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 number
237 following the entry type byte, which is an index into the
238 \dotdebugaddr{} section that selects the new base address for
239 subsequent location list entries. A start/end entry contains two
240 unsigned LEB128 numbers following the entry type byte, which are
241 indices into the \dotdebugaddr{} section that select the beginning
242 and ending addresses. A start/length entry contains one unsigned
243 LEB128 number and a 4-byte unsigned value (as would be
244 represented by the form code \DWFORMdatafour). The first number
245 is an index into the \dotdebugaddr{} section that selects the
246 beginning offset, and the second number is the length of the
247 range. Addresses fetched from the \dotdebugaddr{} section are not
248 relative to the base address. An offset pair entry contains two
249 4-byte unsigned values (as would be represented by the form code
250 \DWFORMdatafour){}, treated as the beginning and ending offsets,
251 respectively, relative to the base address. As in the \dotdebugloc{}
252 section, the base address is obtained either from the nearest
253 preceding base address selection entry, or, if there is no such
254 entry, from the compilation unit base address (as defined in
255 Section 3.1.1). For the latter three types (start/end,
256 start/length, and offset pair), the two operand values are
257 followed by a location description as in a normal location list
258 entry in the \dotdebugloc{} section.
259
260 This design depends on having an index of debugging information
261 available to the consumer. For name lookups, the consumer can use
262 the \dotdebugpubnames{} and \dotdebugpubtypes{} sections (or an index
263 built at link time based on the information in those sections),
264 which will lead to a skeleton compilation unit. The
265 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
266 compilation unit can then be used to locate the corresponding
267 DWARF object file for the compilation unit. Similarly, for an
268 address lookup, the consumer can use the \dotdebugaranges{} table,
269 which will also lead to a skeleton compilation unit. For a file
270 and line number lookup, the skeleton compilation units can be
271 used to locate the line number tables.
272
273 \section{Split DWARF Object Examples}
274 \label{app:splitdwarfobjectexamples}
275
276 TBD