c4160f8c41911eb826fa75409b4227fbe6384627
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
1 \chapter[Split DWARF Object Files (Informative)]{Split DWARF Object Files (Informative)}
2 \label{app:splitdwarfobjectsinformative}
3 \addtoindexx{DWARF compression}
4 \addtoindexx{DWARF duplicate elimination|see{\textit{also} DWARF compression}}
5 \addtoindexx{DWARF duplicate elimination|see{\textit{also} split DWARF object file}}
6 With the traditional DWARF format, debug information is designed
7 with the expectation that it will be processed by the linker to
8 produce an output binary with complete debug information, and
9 with fully-resolved references to locations within the
10 application. For very large applications, however, this approach
11 can result in excessively large link times and excessively large
12 output files. 
13
14 Several vendors have independently developed
15 proprietary approaches that allow the debug information to remain
16 in the relocatable object files, so that the linker does not have
17 to process the debug information or copy it to the output file.
18 These approaches have all required that additional information be
19 made available to the debug information consumer, and that the
20 consumer perform some minimal amount of relocation in order to
21 interpret the debug info correctly. The additional information
22 required, in the form of load maps or symbol tables, and the
23 details of the relocation are not covered by the DWARF
24 specification, and vary with each vendor's implementation.
25
26 Section \refersec{datarep:splitdwarfobjectfiles} describes a new
27 platform-independent mechanism that allows a producer to
28 split the debugging information into relocatable and
29 non-relocatable partitions. This Appendix describes the use
30 of \splitDWARFobjectfile{s} and provides some illustrative
31 examples.
32
33 \section{Overview}
34 \label{app:splitoverview}
35 \DWARFVersionV{} introduces an optional set of debugging sections
36 that allow the compiler to partition the debugging information
37 into a set of (small) sections that require link-time relocation
38 and a set of (large) sections that do not. The sections that
39 require relocation are written to the relocatable object file as
40 usual, and are linked into the final executable. The sections
41 that do not require relocation, however, can be written to the
42 relocatable object (.o) file but ignored by the linker, or they
43 can be written to a separate DWARF object (.dwo{}) 
44 \addtoindexx{\texttt{.dwo} file extension} file.
45
46 \needlines{4}
47 The optional set of debugging sections includes the following:
48 \begin{itemize}
49 \item
50 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
51 \DWTAGtypeunit{} DIEs and
52 their descendants. This is the bulk of the debugging
53 information for the compilation unit that is normally found
54 in the \dotdebuginfo{} section.
55 \item
56 \dotdebugabbrevdwo{} - Contains the abbreviations tables used by
57 the \dotdebuginfodwo{} sections.
58 \item
59 \dotdebuglocdwo{} - Contains the location lists referenced by
60 the debugging information entries in the \dotdebuginfodwo{}
61 section. This contains the location lists normally found in 
62 the \dotdebugloc{} section,
63 with a slightly modified format to eliminate the need for
64 relocations.
65 \item
66 \dotdebugstrdwo{} - Contains the string table for all indirect
67 strings referenced by the debugging information in the
68 \dotdebuginfodwo{} sections.
69 \item
70 \dotdebugstroffsetsdwo{} - Contains the string offsets table
71 for the strings in the \dotdebugstrdwo{}{} section.
72 \item
73 \dotdebugmacrodwo{} - Contains macro definition information,
74 normally found in the \dotdebugmacro{} section.
75 \item
76 \dotdebuglinedwo{} - Contains \addtoindex{specialized line number table}s 
77 for the type units in the \dotdebuginfodwo{} section. These tables
78 contain only the directory and filename lists needed to
79 interpret \DWATdeclfile{} attributes in the debugging
80 information entries. Actual line number tables remain in the
81 \dotdebugline{} section, and remain in the relocatable object
82 (.o) files.
83
84 \end{itemize}
85
86 In a .dwo file there is no benefit to having a separate string
87 section for directories and file names because the primary
88 string table will never be stripped. Accordingly, no
89 \texttt{.debug\_line\_str.dwo} is defined. Content descriptions corresponding
90 to \DWFORMlinestrp{} in an executable file (for example, in the
91 skeleton compilation unit) instead use \DWFORMstrx. This allows
92 directory and file name strings to be merged with general
93 strings and across compilations in package files (which are not
94 subject to potential stripping).
95
96
97
98 In order for the consumer to locate and process the debug
99 information, the compiler must produce a small amount of debug
100 information that passes through the linker into the output
101 binary. A skeleton \dotdebuginfo{} section for each compilation unit
102 contains a reference to the corresponding \texttt{.o} or \texttt{.dwo}
103 file, and the \dotdebugline{} section (which is typically small
104 compared to the \dotdebuginfo{} sections) is
105 linked into the output binary, as is the new \dotdebugaddr{}
106 section.
107
108 \needlines{6}
109 The debug sections that continue to be linked into the
110 output binary include the following:
111 \begin{itemize}
112 \item
113 \dotdebugabbrev{} - Contains the abbreviation codes used by the
114 skeleton \dotdebuginfo{} section.
115 \item
116 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
117 but no children.
118 \item
119 \dotdebugstr{} - Contains any strings referenced by the skeleton
120 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
121 \item
122 \dotdebugstroffsets{} - Contains the string offsets table for
123 the strings in the \dotdebugstr{} section.
124 \item
125 \dotdebugaddr{} - Contains references to loadable sections,
126 indexed by attributes of form \DWFORMaddrx{} or location
127 expression \DWOPaddrx{} opcodes.
128 \item
129 \dotdebugline{} - Contains the line number tables, unaffected by
130 this design. (These could be moved to the .dwo file, but in
131 order to do so, each \DWLNEsetaddress{} opcode would need to
132 be replaced by a new opcode that referenced an entry in the
133 \dotdebugaddr{} section. Furthermore, leaving this section in the
134 .o file allows many debug info consumers to remain unaware of
135 .dwo files.)
136 \item
137 \dotdebugframe{} - Contains the frame tables, unaffected by this
138 design.
139 \item
140 \dotdebugranges{} - Contains the range lists, unaffected by this
141 design.
142 \item
143 \dotdebugnames{} - Contains the names for use in
144 building an index section. This section has the same
145 format and use as always. The section header refers to a
146 compilation unit offset, which is the offset of the
147 skeleton compilation unit in the \dotdebuginfo{} section.
148 \item
149 \dotdebugaranges{} - Contains the accelerated range lookup table
150 for the compilation unit, unaffected by this design.
151 \end{itemize}
152
153 \needlines{6}
154 The skeleton \DWTAGcompileunit{} DIE has the following attributes:
155 \autocols[0pt]{c}{3}{l}{
156 \DWATaddrbase{},
157 \DWATcompdir{},
158 \DWATdwoname{},
159 \DWATdwoid{},
160 \DWAThighpc{} \dag,
161 \DWATlowpc{} \dag,
162 \DWATranges{} \dag,
163 \DWATrangesbase{},
164 \DWATstmtlist{},
165 \DWATstroffsetsbase{}
166 }
167 \dag{} If \DWATranges{} is present, the \DWATlowpc{}/\DWAThighpc{}
168 pair is not used, although \DWATlowpc{} may still be present
169 to provide a default base address for range list entries.
170 Conversely, if the \DWATlowpc/\linebreak[0]\DWAThighpc{} pair is
171 present, then \DWATranges{} is not used.
172
173 All other attributes of the compilation unit DIE are moved to
174 the full DIE in the \dotdebuginfodwo{} section.
175 The \DWATdwoid{} attribute is present
176 in both the skeleton DIE and the full DIE, so that a consumer
177 can verify a match.
178
179 \needlines{4}
180 Because of other improvements in \DWARFVersionV, most of the
181 relocations that would normally be found in the \dotdebuginfodwo{}
182 sections are moved to the \dotdebugaddr{} and
183 \dotdebugstroffsetsdwo{} sections. Those in the
184 \dotdebugstroffsetsdwo{} sections are simply omitted because the
185 DWARF information in those sections is not combined at link
186 time, so no relocation is necessary. Similarly,
187 many of the remaining relocations referring to range lists are
188 eliminated. 
189
190 The relocations that remain fall into the following categories:
191 \begin{itemize}
192 \item
193 References from compilation unit and type unit headers to the
194 \dotdebugabbrevdwo{} section. Because the new sections are not
195 combined at link time, these references need no relocations.
196 \item
197 References from \DWTAGcompileunit{} DIEs to the
198 \dotdebuglinedwo{} section, via \DWATstmtlist{}. This attribute
199 remains in the skeleton \dotdebuginfo{} section, so no
200 relocation in the \dotdebuginfodwo{} section is necessary.
201 \item
202 References from \DWTAGtypeunit{} DIEs to the skeleton
203 \dotdebuglinedwo{} section, via \DWATstmtlist{}. Because the new
204 sections are not combined at link time, these references need
205 no relocations.
206 \item
207 References from \DWTAGcompileunit{} and \DWTAGtypeunit{} DIEs
208 to the \dotdebugstroffsetsdwo{} section, via
209 \DWATstroffsetsbase{}. Because the new sections are not
210 combined at link time, the \DWATstroffsetsbase{} attribute
211 is not required in a \dotdebuginfodwo{}
212 section.
213 \item
214 References from \DWTAGcompileunit{} DIEs to the \dotdebugaddr{}
215 section, via \DWATaddrbase{}. This attribute remains in
216 the skeleton \dotdebuginfo{} section, so no relocation in the
217 \dotdebuginfodwo{} section is necessary.
218 \needlines{4}
219 \item
220 References from \DWTAGcompileunit{} DIEs to the \dotdebugranges{}
221 section, via \DWATrangesbase{}. This attribute remains in
222 the skeleton \dotdebuginfo{} section, so no relocation in the
223 \dotdebuginfodwo{} section is necessary.
224 \item
225 References from the \dotdebuglocdwo{} section to machine addresses
226 via a location list entry or a base address selection entry.
227 With a minor change to the location list entry format,
228 described below, these relocations are also eliminated.
229 \end{itemize}
230
231 \needlines{4}
232 Each location list entry contains beginning and ending address
233 offsets, which normally may be relocated addresses. In the
234 \dotdebuglocdwo{} section, these offsets are replaced by indices
235 into the \dotdebugaddr{} section. Each location list entry begins
236 with a single byte identifying the entry type:
237 \begin{itemize}
238 \item
239 \DWLLEendoflistentry{} (0) indicates an end-of-list entry,
240 \item
241 \DWLLEbaseaddressselectionentry{} (1) indicates a base address
242 selection entry, 
243 \item
244 \DWLLEstartendentry{} (2) indicates a normal
245 location list entry providing start and end addresses,
246 \item
247 \DWLLEstartlengthentry{} (3) indicates a normal location list
248 entry providing a start address and a length, and
249 \item
250 \DWLLEoffsetpairentry{} (4) indicates a normal location list
251 entry providing start and end offsets relative to the base
252 address. 
253 \end{itemize}
254 An end-of-list entry has no further data. A base address
255 selection entry contains a single unsigned LEB128
256 \addtoindexx{LEB128!unsigned} number
257 following the entry type byte, which is an index into the
258 \dotdebugaddr{} section that selects the new base address for
259 subsequent location list entries. A start/end entry contains two
260 unsigned LEB128\addtoindexx{LEB128!unsigned} numbers 
261 following the entry type byte, which are
262 indices into the \dotdebugaddr{} section that select the beginning
263 and ending addresses. A start/length entry contains one unsigned
264 LEB128 number and a 4-byte unsigned value (as would be
265 represented by the form code \DWFORMdatafour). The first number
266 is an index into the \dotdebugaddr{} section that selects the
267 beginning offset, and the second number is the length of the
268 range. Addresses fetched from the \dotdebugaddr{} section are not
269 relative to the base address. An offset pair entry contains two
270 4-byte unsigned values (as would be represented by the form code
271 \DWFORMdatafour){}, treated as the beginning and ending offsets,
272 respectively, relative to the base address. As in the \dotdebugloc{}
273 section, the base address is obtained either from the nearest
274 preceding base address selection entry, or, if there is no such
275 entry, from the compilation unit base address (as defined in
276 Section \refersec{chap:normalandpartialcompilationunitentries}). 
277 For the latter three types (start/end,
278 start/length, and offset pair), the two operand values are
279 followed by a location description as in a normal location list
280 entry in the \dotdebugloc{} section.
281
282 \needlines{8}
283 This design depends on having an index of debugging information
284 available to the consumer. For name lookups, the consumer can 
285 use the \dotdebugnames{} index section (see 
286 Section \refersec{chap:acceleratedaccess}) to 
287 locate a skeleton compilation unit. The
288 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
289 compilation unit can then be used to locate the corresponding
290 DWARF object file for the compilation unit. Similarly, for an
291 address lookup, the consumer can use the \dotdebugaranges{} table,
292 which will also lead to a skeleton compilation unit. For a file
293 and line number lookup, the skeleton compilation units can be
294 used to locate the line number tables.
295
296 \section{Split DWARF Object File Example}
297 \label{app:splitdwarfobjectfileexample}
298 \addtoindexx{split DWARF object file!example}
299 Consider the example source code in 
300 Figure \refersec{fig:splitobjectexamplesourcefragment1}, 
301 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
302 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
303 When compiled with split DWARF, we will have two object files,
304 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s}, 
305 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
306
307 \begin{figure}[b]
308 \textit{File demo1.cc}
309 \begin{lstlisting}
310 #include "demo.h"
311
312 bool Box::contains(const Point& p) const
313 {
314     return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
315             p.y() >= ll_.y() && p.y() <= ur_.y());
316 }
317 \end{lstlisting}
318 \caption{Split object example: source fragment \#1}
319 \label{fig:splitobjectexamplesourcefragment1}
320 \end{figure}
321
322 \begin{figure}[h]
323 \textit{File demo2.cc}
324 \begin{lstlisting}
325 #include "demo.h"
326
327 bool Line::clip(const Box& b)
328 {
329   float slope = (end_.y() - start_.y()) / (end_.x() - start_.x());
330   while (1) {
331     // Trivial acceptance.
332     if (b.contains(start_) && b.contains(end_)) return true;
333
334     // Trivial rejection.
335     if (start_.x() < b.l() && end_.x() < b.l()) return false;
336     if (start_.x() > b.r() && end_.x() > b.r()) return false;
337     if (start_.y() < b.b() && end_.y() < b.b()) return false;
338     if (start_.y() > b.t() && end_.y() > b.t()) return false;
339
340     if (b.contains(start_)) {
341       // Swap points so that start_ is outside the clipping 
342       // rectangle.
343       Point temp = start_;
344       start_ = end_;
345       end_ = temp;
346     }
347
348     if (start_.x() < b.l())
349       start_ = Point(b.l(), 
350                      start_.y() + (b.l() - start_.x()) * slope);
351     else if (start_.x() > b.r())
352       start_ = Point(b.r(), 
353                      start_.y() + (b.r() - start_.x()) * slope);
354     else if (start_.y() < b.b())
355       start_ = Point(start_.x() + (b.b() - start_.y()) / slope, 
356                      b.b());
357     else if (start_.y() > b.t())
358       start_ = Point(start_.x() + (b.t() - start_.y()) / slope, 
359                      b.t());
360   }
361 }
362 \end{lstlisting}
363 \caption{Split object example: source fragment \#2}
364 \label{fig:splitobjectexamplesourcefragment2}
365 \end{figure}
366
367 \begin{figure}[h]
368 \textit{File demo.h}
369 \begin{lstlisting}
370 class A {
371   public:
372     Point(float x, float y) : x_(x), y_(y){}
373     float x() const { return x_; }
374     float y() const { return y_; }
375   private:
376     float x_;
377     float y_;
378 };
379
380 class Line {
381   public:
382     Line(Point start, Point end) : start_(start), end_(end){}
383     bool clip(const Box& b);
384     Point start() const { return start_; }
385     Point end() const { return end_; }
386   private:
387     Point start_;
388     Point end_;
389 };
390
391 class Box {
392   public:
393     Box(float l, float r, float b, float t) : ll_(l, b), ur_(r, t){}
394     Box(Point ll, Point ur) : ll_(ll), ur_(ur){}
395     bool contains(const Point& p) const;
396     float l() const { return ll_.x(); }
397     float r() const { return ur_.x(); }
398     float b() const { return ll_.y(); }
399     float t() const { return ur_.y(); }
400   private:
401     Point ll_;
402     Point ur_;
403 };
404
405 \end{lstlisting}
406 \caption{Split object example: source fragment \#3}
407 \label{fig:splitobjectexamplesourcefragment3}
408 \end{figure}
409
410 \clearpage
411 \subsection{Contents of the Object File}
412 The object files each contain the following sections of debug
413 information:
414 \begin{alltt}
415   \dotdebugabbrev
416   \dotdebuginfo
417   \dotdebugranges
418   \dotdebugline
419   \dotdebugstr
420   \dotdebugaddr
421   \dotdebugnames
422   \dotdebugaranges
423 \end{alltt}
424
425 The \dotdebugabbrev{} section contains just a single entry describing
426 the skeleton compilation unit DIE.
427
428 The DWARF description in the \dotdebuginfo{} section 
429 contains just a single DIE, the skeleton compilation unit, 
430 which may look like 
431 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
432
433 \begin{figure}[h]
434 \begin{dwflisting}
435 \begin{alltt}
436
437     \DWTAGcompileunit
438       \DWATcompdir: (reference to directory name in .debug_str)
439       \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
440       \DWATdwoid: 0x44e413b8a2d1b8f
441       \DWATaddrbase: (reference to .debug_addr section)
442       \DWATrangesbase: (reference to range list in .debug_ranges section)
443       \DWATranges: (offset of range list in .debug_ranges section)
444       \DWATstmtlist: (reference to .debug_line section)
445       \DWATlowpc: 0
446       
447 \end{alltt}
448 \end{dwflisting}
449 \caption{Split object example: Skeleton DWARF description}
450 \label{fig:splitdwafexampleskeletondwarfdescription}
451 \end{figure}
452
453 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
454 location of the corresponding \splitDWARFobjectfile{} that
455 contains the full debug information; that file is normally
456 expected to be in the same directory as the object file itself.
457
458 The \DWATdwoid{} attribute provides a hash of the debug
459 information contained in the \splitDWARFobjectfile. This hash serves
460 two purposes: it can be used to verify that the debug information
461 in the \splitDWARFobjectfile{} matches the information in the object
462 file, and it can be used to find the debug information in a DWARF
463 package file.
464
465 \needlines{4}
466 The \DWATaddrbase{} attribute contains the relocatable offset of
467 this object file's contribution to the \dotdebugaddr{} section, and
468 the \DWATrangesbase{} attribute contains the relocatable offset
469 of this object file's contribution to the \dotdebugranges{} section.
470 The \DWATranges{} attribute refers to a specific range list within
471 that contribution, and its value is a (non-relocatable) offset
472 relative to the base. In a compilation unit with a single
473 contiguous range of code, the \DWATranges{} attribute might be
474 omitted, and instead replaced by the pair \DWATlowpc{} and
475 \DWAThighpc.
476
477 The \DWATstmtlist{} attribute contains the relocatable offset of
478 this file's contribution to the \dotdebugline{} table.
479
480 If there is a \DWATranges{} attribute, the \DWATlowpc{} attribute
481 provides a default base address for the range list entries in the
482 \dotdebugranges{} section. It may be omitted if each range list entry
483 provides an explicit base address selection entry; it may provide
484 a relocatable base address, in which case the offsets in each
485 range list entry are relative to it; or it may have the value 0,
486 in which case the offsets in each range list entry are themselves
487 relocatable addresses.
488
489 The \dotdebugranges{} section contains the range list referenced by
490 the \DWATranges{} attribute in the skeleton compilation unit DIE,
491 plus any range lists referenced by \DWATranges{} attributes in the
492 split DWARF object. In our example, \texttt{demo1.o} would contain range
493 list entries for the function \texttt{Box::contains}, as well as for
494 out-of-line copies of the inline functions \texttt{Point::x} and 
495 \texttt{Point::y}.
496
497 The \dotdebugline{} section contains the full line number table for
498 the compiled code in the object file. In the example in
499 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
500 number program header would list the two files, \texttt{demo.h} and
501 \texttt{demo1.cc}, and would contain line number programs for
502 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
503
504 The \dotdebugstr{} section contains the strings referenced indirectly
505 by the compilation unit DIE and by the line number program.
506
507 The \dotdebugaddr{} section contains relocatable addresses of
508 locations in the loadable text and data that are referenced by
509 debugging information entries in the split DWARF object. In the
510 example in \refersec{fig:splitobjectexamplesourcefragment3}, 
511 \texttt{demo1.o} may have three entries:
512 \begin{center}
513 %\footnotesize
514 \begin{tabular}{cl}
515 Slot & Location referenced \\
516 \hline
517    0   &  low PC value for \texttt{Box::contains}  \\
518    1   &  low PC value for \texttt{Point::x}       \\
519    2   &  low PC value for \texttt{Point::y}       \\
520 \end{tabular}
521 \end{center}
522
523 \needlines{4}
524 The \dotdebugnames{}
525 section contains the names defined by the debugging
526 information in the \splitDWARFobjectfile{} 
527 (see Section \refersec{chap:contentsofthenameindex}, 
528 and references the skeleton compilation unit. 
529 When linked together into a final executable,
530 they can be used by a DWARF consumer to lookup a name to find one
531 or more skeleton compilation units that provide information about
532 that name. From the skeleton compilation unit, the consumer can
533 find the \splitDWARFobjectfile{} that it can then read to get the full
534 DWARF information.
535
536 The \dotdebugaranges{} section contains the PC ranges defined in this
537 compilation unit, and allow a DWARF consumer to map a PC value to
538 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
539
540
541 \subsection{Contents of the Split DWARF Object Files}
542 The \splitDWARFobjectfile{s} each contain the following sections:
543 \begin{alltt}
544   \dotdebugabbrevdwo
545   \dotdebuginfodwo{} (for the compilation unit)
546   \dotdebuginfodwo{} (one COMDAT section for each type unit)
547   \dotdebuglocdwo
548   \dotdebuglinedwo
549   \dotdebugmacrodwo
550   \dotdebugstroffsetsdwo
551   \dotdebugstrdwo
552 \end{alltt}
553 The \dotdebugabbrevdwo{} section contains the abbreviation
554 declarations for the debugging information entries in the
555 \dotdebuginfodwo{} section. In general, it looks just like a normal
556 \dotdebugabbrev{} section in a non-split object file.
557
558 The \dotdebuginfodwo{} section containing the compilation unit
559 contains the full debugging information for the compile unit, and
560 looks much like a normal \dotdebuginfo{} section in a non-split
561 object file, with the following exceptions:
562 \begin{itemize}
563 \item The \DWTAGcompileunit{} DIE does not need to repeat the
564 \DWATranges, \DWATlowpc, \DWAThighpc, and
565 \DWATstmtlist{} attributes that are provided in the skeleton
566 compilation unit.
567
568 \item References to strings in the string table use the new form
569 code \DWFORMstrx, referring to slots in the
570 \dotdebugstroffsetsdwo{} section.
571
572 \textit{Use of \DWFORMstrp{} is not appropriate in a \splitDWARFobjectfile.}
573
574 \needlines{4}
575 \item References to range lists in the \dotdebugranges{} section are
576 all relative to the base offset given by \DWATrangesbase{}
577 in the skeleton compilation unit.
578
579 \item References to relocatable addresses in the object file use
580 the new form code \DWFORMaddrx, referring to slots in the
581 \dotdebugaddr{} table, relative to the base offset given by
582 \DWATaddrbase{} in the skeleton compilation unit.
583 \end{itemize}
584
585 Figure \refersec{fig:splitobjectexampledemo1dwodwarfexcerpts} presents
586 some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
587
588 \begin{figure}[h]
589 \figurepart{1}{2}
590 \begin{dwflisting}
591 \begin{alltt}
592
593     \DWTAGcompileunit
594         \DWATproducer [\DWFORMstrx]: (slot 15) (producer string)
595         \DWATlanguage: \DWLANGCplusplus
596         \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
597         \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
598         \DWATdwoid [\DWFORMdataeight]: 0x44e413b8a2d1b8f
599 1$:   \DWTAGclasstype
600           \DWATname [\DWFORMstrx]: (slot 12) "Point"
601           \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
602           \DWATdeclaration: true
603 2$:     \DWTAGsubprogram
604           \DWATexternal: true
605           \DWATname [\DWFORMstrx]: (slot 12) "Point"
606           \DWATdeclfile: 1
607           \DWATdeclline: 5
608           \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff"
609           \DWATaccessibility: \DWACCESSpublic
610           \DWATdeclaration: true
611         ...
612 3$:   \DWTAGclasstype
613           \DWATname [\DWFORMstring]: "Box"
614           \DWATsignature [\DWFORMrefsigeight]: 0xe97a3917c5a6529b
615           \DWATdeclaration: true
616         ...
617 4$:     \DWTAGsubprogram
618             \DWATexternal: true
619             \DWATname [\DWFORMstrx]: (slot 0) "contains"
620             \DWATdeclfile: 1
621             \DWATdeclline: 28
622             \DWATlinkagename [\DWFORMstrx]: (slot 8) "_ZNK3Box8containsERK5Point"
623             \DWATtype: (reference to 7$)
624             \DWATaccessibility: \DWACCESSpublic
625             \DWATdeclaration: true
626         ...
627 \end{alltt}
628 \end{dwflisting}
629 \caption{Split object example: \texttt{demo1.dwo} excerpts}
630 \label{fig:splitobjectexampledemo1dwodwarfexcerpts}
631 \end{figure}
632         
633 \begin{figure}
634 \figurepart{2}{2}
635 \begin{dwflisting}
636 \begin{alltt}
637
638 5$:   \DWTAGsubprogram
639           \DWATspecification: (reference to 4$)
640           \DWATdeclfile: 2
641           \DWATdeclline: 3
642           \DWATlowpc [\DWFORMaddrx]: (slot 0)
643           \DWAThighpc [\DWFORMdataeight]: 0xbb
644           \DWATframebase: \DWOPcallframecfa
645           \DWATobjectpointer: (reference to 6$)
646 6$:     \DWTAGformalparameter
647             \DWATname [\DWFORMstrx]: (slot 13): "this"
648             \DWATtype: (reference to 8$)
649             \DWATartificial: true
650             \DWATlocation: \DWOPfbreg(-24)
651         \DWTAGformalparameter
652             \DWATname [\DWFORMstring]: "p"
653             \DWATdeclfile: 2
654             \DWATdeclline: 3
655             \DWATtype: (reference to 11$)
656             \DWATlocation: \DWOPfbreg(-32)
657       ...
658 7$:   \DWTAGbasetype
659           \DWATbytesize: 1
660           \DWATencoding: \DWATEboolean
661           \DWATname [\DWFORMstrx]: (slot 5) "bool"
662       ...
663 8$:   \DWTAGconsttype
664           \DWATtype: (reference to 9$)
665 9$:   \DWTAGpointertype
666           \DWATbytesize: 8
667           \DWATtype: (reference to 10$)
668 10$:  \DWTAGconsttype
669           \DWATtype: (reference to 3$)
670       ...
671 11$:  \DWTAGconsttype
672           \DWATtype: (reference to 12$)
673 12$:  \DWTAGreferencetype
674           \DWATbytesize: 8
675           \DWATtype: (reference to 13$)
676 13$:  \DWTAGconsttype
677           \DWATtype: (reference to 1$)
678       ...
679 \end{alltt}
680 \end{dwflisting}
681 \begin{center}
682 \vspace{3mm}
683 Figure~\ref{fig:splitobjectexampledemo1dwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
684 \end{center}
685 \end{figure}
686
687 In the defining declaration for \texttt{Box::contains} at 5\$, the
688 \DWATlowpc{} attribute is represented with \DWFORMaddrx,
689 referring to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
690 That slot contains the relocated address of the beginning of the
691 function.
692
693 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
694 section, and looks like a normal type unit in a non-split object,
695 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
696 attribute that refers to a specialized \dotdebuglinedwo{}
697 \addtoindexx{type unit!specialized \texttt{.debug\_line.dwo} section in}
698 \addtoindexx{specialized \texttt{.debug\_line.dwo} section}
699 section. This
700 section contains a normal line number
701 program header with a list of include directories and filenames,
702 but no line number program. This section is used only as a
703 reference for filenames needed for \DWATdeclfile{} attributes
704 within the type unit.
705
706 The \dotdebugstroffsetsdwo{} section contains an entry for each
707 unique string in the string table. In the \texttt{demo1.dwo} example,
708 these string table slots have been assigned as shown in
709 Figure \refersec{fig:splitobjectexamplestringtableslots}.
710
711 \begin{figure}[H]
712 \begin{center}
713 \footnotesize
714 \begin{tabular}{cl|cl}
715     Slot & String & Slot & String \\
716     \hline
717     0  &   contains                         &    10 &   \_ZNK3Box1rEv \\
718     1  &   \_ZNK5Point1xEv                  &    11 &   \_ZN3BoxC4E5PointS0\_ \\
719     2  &   \_ZNK3Box1lEv                    &    12 &   Point\\
720     3  &   \_ZNK3Box1bEv                    &    13 &   this\\
721     4  &   \textit{(compilation directory)} &    14 &   float \\
722     5  &   bool                             &    15 &   \textit{(producer string)} \\
723     6  &   \_ZN3BoxC4Effff                  &    16 &   \_ZN5PointC4Eff \\
724     7  &   demo1.cc                         &    17 &   \_ZNK3Box1tEv \\
725     8  &   \_ZNK3Box8containsERK5Point      & \\
726     9  &   \_ZNK5Point1yEv                  & \\
727 \end{tabular}
728 \end{center}
729 \caption{Split object example: String table slots}
730 \label{fig:splitobjectexamplestringtableslots}
731 \end{figure}
732
733 Each entry in the table is the offset of the string, which is
734 contained in the \dotdebugstrdwo{} section. In a split DWARF 
735 object file, these offsets have no relocations, since they 
736 are not part of the relocatable object file. When combined into a 
737 DWARF package file, however, each slot must be adjusted to 
738 refer to the appropriate offset within the merged string table.
739 The tool that builds the DWARF package file must understand 
740 the structure of the section in order to apply the necessary 
741 adjustments. (See Section \refersec{app:dwarfpackagefileexample} 
742 for an example of a DWARF package file.)
743
744 \needlines{4}
745 The \dotdebuglocdwo{} section contains the location lists referenced
746 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
747 section has a similar format to the \dotdebugloc{} section in a
748 non-split object, but it has some small differences as explained
749 in Section \refersec{datarep:locationlistentriesinsplitobjects}. 
750 In \texttt{demo2.dwo} as shown in 
751 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}, 
752 the debugging information for \texttt{Line::clip} describes a local 
753 variable \texttt{slope} whose location varies based on the PC.
754 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts} 
755 presents some excerpts from the \dotdebuginfodwo{} section for 
756 \texttt{demo2.dwo}.
757
758 \begin{figure}[b]
759 \figurepart{1}{2}
760 \begin{dwflisting}
761 \begin{alltt}
762
763 1$: \DWTAGclasstype
764         \DWATname [\DWFORMstrx]: (slot 20) "Line"
765         \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
766         \DWATdeclaration: true
767     ...
768 2$:   \DWTAGsubprogram
769           \DWATexternal: true
770           \DWATname [\DWFORMstrx]: (slot 19) "clip"
771           \DWATdeclfile: 2
772           \DWATdeclline: 16
773           \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
774           \DWATtype: (reference to DIE for bool)
775           \DWATaccessibility: \DWACCESSpublic
776           \DWATdeclaration: true
777       ...
778 \end{alltt}
779 \end{dwflisting}
780 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
781 \label{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}
782 \end{figure}
783
784 \begin{figure}
785 \figurepart{2}{2}
786 \begin{dwflisting}
787 \begin{alltt}
788
789 3$:   \DWTAGsubprogram
790           \DWATspecification: (reference to 2$)
791           \DWATdeclfile: 1
792           \DWATdeclline: 3
793           \DWATlowpc [\DWFORMaddrx]: (slot 32)
794           \DWAThighpc [\DWFORMdataeight]: 0x1ec
795           \DWATframebase: \DWOPcallframecfa
796           \DWATobjectpointer: (reference to 4$)
797 4$:     \DWTAGformalparameter
798             \DWATname: (indexed string: 0x11): this
799             \DWATtype: (reference to DIE for type const Point* const)
800             \DWATartificial: 1
801             \DWATlocation: 0x0 (location list)
802 5$:     \DWTAGformalparameter
803             \DWATname: b
804             \DWATdeclfile: 1
805             \DWATdeclline: 3
806             \DWATtype: (reference to DIE for type const Box& const)
807             \DWATlocation [\DWFORMsecoffset]: 0x2a
808 6$:     \DWTAGlexicalblock
809             \DWATlowpc [\DWFORMaddrx]: (slot 17)
810             \DWAThighpc: 0x1d5
811 7$:       \DWTAGvariable
812               \DWATname [\DWFORMstrx]: (slot 28): "slope"
813               \DWATdeclfile: 1
814               \DWATdeclline: 5
815               \DWATtype: (reference to DIE for type float)
816               \DWATlocation [\DWFORMsecoffset]: 0x49
817
818 \end{alltt}
819 \end{dwflisting}
820 \begin{center}
821 \vspace{3mm}
822 Figure~\ref{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
823 \end{center}
824 \end{figure}
825
826 In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts},
827 The \DWTAGformalparameter{} entries at 4\$ and 5\$ refer to the
828 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
829 \DWTAGvariable{} entry for \texttt{slope} at 7\$ refers to the location
830 list at offset \texttt{0x49}. 
831 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
832 shows a representation of the
833 location lists at those offsets in the \dotdebuglocdwo{} section.
834
835 \begin{figure}
836 \begin{dwflisting}
837 \begin{tabular}{rlrrl}
838 \texttt{offset} & entry type & start & length & expression \\
839 \hline \\
840 0x00 & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfive~(rdi) \\
841 0x09 & \DWLLEstartlengthentry & [11] & 0x01b9 & \DWOPregthree~(rbx) \\
842 0x12 & \DWLLEstartlengthentry & [29] & 0x0003 & \DWOPbregtwelve~(r12):\\
843 &&&& -8; \DWOPstackvalue \\
844 0x1d & \DWLLEstartlengthentry & [31] & 0x0001 & \DWOPentryvalue: \\
845 &&&& (\DWOPregfive~(rdi)); \\
846 &&&& \DWOPstackvalue \\
847 0x29 & \DWLLEendoflistentry &&& \\
848 \\   & \hhline{-} &&& \\
849 0x2a & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfour~(rsi)) \\
850 0x33 & \DWLLEstartlengthentry & [11] & 0x01ba & \DWOPregsix~(rbp)) \\
851 0x3c & \DWLLEstartlengthentry & [30] & 0x0003 & \DWOPentryvalue: \\
852 &&&& (\DWOPregfour~(rsi)); \\
853 &&&& \DWOPstackvalue \\
854 0x48 & \DWLLEendoflistentry &&& \\
855 \\   & \hhline{-} &&& \\
856 0x49 & \DWLLEstartlengthentry & [10] & 0x0004 & \DWOPregeighteen~(xmm1) \\
857 0x52 & \DWLLEstartlengthentry & [11] & 0x01bd & \DWOPfbreg: -36 \\
858 0x5c & \DWLLEendoflistentry &&& \\
859 &&&& \\
860 \end{tabular}
861 \end{dwflisting}
862 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
863 \label{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
864 \end{figure}
865
866 In each \DWLLEstartlengthentry{}, the start field is the index
867 of a slot in the \dotdebugaddr{} section, relative to the base
868 offset defined by the compilations unit's \DWATaddrbase{}
869 attribute. The \dotdebugaddr{} slots referenced by these entries give
870 the relocated address of a label within the function where the
871 address range begins. The length field gives the length of the
872 address range.
873
874 \clearpage
875 \section{DWARF Package File Example}
876 \label{app:dwarfpackagefileexample}
877 \addtoindexx{DWARF duplicate elimination!examples}
878 [TBD]