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