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