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