Working copy for backup...
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
1 \chapter[Split DWARF Object Files (Informative)]{Split DWARF Object Files (Informative)}
2 \label{app:splitdwarfobjectsinformative}
3 \addtoindexx{DWARF compression}
4 \addtoindexx{DWARF duplicate elimination|see{\textit{also} DWARF compression}}
5 \addtoindexx{DWARF duplicate elimination|see{\textit{also} split DWARF object file}}
6 With the traditional DWARF format, debug information is designed
7 with the expectation that it will be processed by the linker to
8 produce an output binary with complete debug information, and
9 with fully-resolved references to locations within the
10 application. For very large applications, however, this approach
11 can result in excessively large link times and excessively large
12 output files. 
13
14 Several vendors have independently developed
15 proprietary approaches that allow the debug information to remain
16 in the relocatable object files, so that the linker does not have
17 to process the debug information or copy it to the output file.
18 These approaches have all required that additional information be
19 made available to the debug information consumer, and that the
20 consumer perform some minimal amount of relocation in order to
21 interpret the debug info correctly. The additional information
22 required, in the form of load maps or symbol tables, and the
23 details of the relocation are not covered by the DWARF
24 specification, and vary with each vendor's implementation.
25
26 Section \refersec{datarep:splitdwarfobjectfiles} describes a
27 platform-independent mechanism that allows a producer to
28 split the debugging information into relocatable and
29 non-relocatable partitions. This Appendix describes the use
30 of \splitDWARFobjectfile{s} and provides some illustrative
31 examples.
32
33 \section{Overview}
34 \label{app:splitoverview}
35 \DWARFVersionV{} introduces an optional set of debugging sections
36 that allow the compiler to partition the debugging information
37 into a set of (small) sections that require link-time relocation
38 and a set of (large) sections that do not. The sections that
39 require relocation are written to the relocatable object file as
40 usual, and are linked into the final executable. The sections
41 that do not require relocation, however, can be written to the
42 relocatable object (.o) file but ignored by the linker, or they
43 can be written to a separate DWARF object (.dwo{}) 
44 \addtoindexx{\texttt{.dwo} file extension} file.
45
46 \needlines{4}
47 The optional set of debugging sections includes the following:
48 \begin{itemize}
49 \item
50 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
51 \DWTAGtypeunit{} DIEs and
52 their descendants. This is the bulk of the debugging
53 information for the compilation unit that is normally found
54 in the \dotdebuginfo{} section.
55 \item
56 \dotdebugabbrevdwo{} - Contains the abbreviations table(s) used by
57 the \dotdebuginfodwo{} section.
58 \item
59 \dotdebuglocdwo{} - Contains the location lists referenced by
60 the debugging information entries in the \dotdebuginfodwo{}
61 section. This contains the location lists normally found in 
62 the \dotdebugloc{} section,
63 with a slightly modified format to eliminate the need for
64 relocations.
65 \item
66 \dotdebugstrdwo{} - Contains the string table for all indirect
67 strings referenced by the debugging information in the
68 \dotdebuginfodwo{} sections.
69 \item
70 \dotdebugstroffsetsdwo{} - Contains the string offsets table
71 for the strings in the \dotdebugstrdwo{}{} section.
72 \item
73 \dotdebugmacrodwo{} - Contains macro definition information,
74 normally found in the \dotdebugmacro{} section.
75 \item
76 \dotdebuglinedwo{} - Contains \addtoindex{specialized line number table}s 
77 for the type units in the \dotdebuginfodwo{} section. These tables
78 contain only the directory and filename lists needed to
79 interpret \DWATdeclfile{} attributes in the debugging
80 information entries. Actual line number tables remain in the
81 \dotdebugline{} section, and remain in the relocatable object
82 (.o) files.
83
84 \end{itemize}
85
86 In a \texttt{.dwo} file, there is no benefit to having a separate string
87 section for directories and file names because the primary
88 string table will never be stripped. Accordingly, no
89 \texttt{.debug\_line\_str.dwo} section is defined. Content descriptions 
90 corresponding to \DWFORMlinestrp{} in an executable file (for example, 
91 in the skeleton compilation unit) instead use \DWFORMstrx. This allows
92 directory and file name strings to be merged with general
93 strings and across compilations in package files (which are not
94 subject to potential stripping).
95
96 In a \texttt{.dwo} file, referring to a string using \DWFORMstrp{}
97 is valid, but such use may complicate incorporation of that file into a
98 \texttt{.dwp} file due to changed string offsets as a result of string merging.
99
100 In order for the consumer to locate and process the debug
101 information, the compiler must produce a small amount of debug
102 information that passes through the linker into the output
103 binary. A skeleton \dotdebuginfo{} section for each compilation unit
104 contains a reference to the corresponding \texttt{.o} or \texttt{.dwo}
105 file, and the \dotdebugline{} section (which is typically small
106 compared to the \dotdebuginfo{} sections) is
107 linked into the output binary, as is the new \dotdebugaddr{}
108 section.
109
110 \needlines{6}
111 The debug sections that continue to be linked into the
112 output binary include the following:
113 \begin{itemize}
114 \item
115 \dotdebugabbrev{} - Contains the abbreviation codes used by the
116 skeleton \dotdebuginfo{} section.
117 \item
118 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
119 but no children.
120 \item
121 \dotdebugstr{} - Contains any strings referenced by the skeleton
122 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
123 \item
124 \dotdebugstroffsets{} - Contains the string offsets table for
125 the strings in the \dotdebugstr{} section (if \DWFORMstrx is used).
126 \item
127 \dotdebugaddr{} - Contains references to loadable sections,
128 indexed by attributes of form \DWFORMaddrx{} or location
129 expression \DWOPaddrx{} opcodes.
130 \item
131 \dotdebugline{} - Contains the line number tables, unaffected by
132 this design. (These could be moved to the .dwo file, but in
133 order to do so, each \DWLNEsetaddress{} opcode would need to
134 be replaced by a new opcode that referenced an entry in the
135 \dotdebugaddr{} section. Furthermore, leaving this section in the
136 .o file allows many debug info consumers to remain unaware of
137 .dwo files.)
138 \item
139 \dotdebugframe{} - Contains the frame tables, unaffected by this
140 design.
141 \item
142 \dotdebugranges{} - Contains the range lists, unaffected by this
143 design.
144 \item
145 \dotdebugnames{} - Contains the names for use in
146 building an index section. This section has the same
147 format and use as always. The section header refers to a
148 compilation unit offset, which is the offset of the
149 skeleton compilation unit in the \dotdebuginfo{} section.
150 \item
151 \dotdebugaranges{} - Contains the accelerated range lookup table
152 for the compilation unit, unaffected by this design.
153 \end{itemize}
154
155 \needlines{6}
156 The skeleton \DWTAGcompileunit{} DIE has the following attributes:
157 \autocols[0pt]{c}{3}{l}{
158 \DWATaddrbase{},
159 \DWATcompdir{},
160 \DWATdwoname{},
161 \DWATdwoid{},
162 \DWAThighpc{} \dag,
163 \DWATlowpc{} \dag,
164 \DWATranges{} \dag,
165 \DWATrangesbase{},
166 \DWATstmtlist{},
167 \DWATstroffsetsbase{}
168 }
169 \dag{} If \DWATranges{} is present, the \DWATlowpc{}/\DWAThighpc{}
170 pair is not used, although \DWATlowpc{} may still be present
171 to provide a default base address for range list entries.
172 Conversely, if the \DWATlowpc/\linebreak[0]\DWAThighpc{} pair is
173 present, then \DWATranges{} is not used.
174
175 All other attributes of the compilation unit DIE are moved to
176 the full DIE in the \dotdebuginfodwo{} section.
177 The \DWATdwoid{} attribute is present
178 in both the skeleton DIE and the full DIE, so that a consumer
179 can verify a match.
180
181 \needlines{4}
182
183 Relocations are neither necessary nor useful in .dwo files, because the
184 .dwo files contain only debugging information that does not need to be
185 processed by a linker. Relocations are rendered unnecessary via
186 four strategies:
187
188 \begin{enumerate}[1. ]
189 \item Some values needing relocation are kept in the \texttt{.o} file
190 (for example, references to the line number program from the skeleton
191 compilation unit).
192
193 \item Some values do not need a relocation because they refer from
194 one \dotdwo{} section to another \dotdwo{} section. Because \texttt{.dwo} files are not
195 combined by the linker, these references are known at compile time and
196 do not need further relocation.
197
198 \item Some values that need a relocation to refer to a
199 relocatable program address use the \DWFORMaddrx{} form,
200 referencing a relocatable value in the \dotdebugaddr{} section (which
201 remains in the \texttt{.o} file).
202
203 \item Some values that need a relocation to refer to the
204 \dotdebugranges{} section in the \texttt{.o} file use a relocatable base
205 specified by the \DWATrangesbase{} attribute (which is placed in the
206 skeleton compilation unit in the \texttt{.o} file).
207
208 \end{enumerate}
209
210
211 Table \refersec{tab:unitattributesbyunitkind} summarizes which
212 attributes are defined for use in the various kind of compilation
213 units.
214
215
216
217 \begin{table}[h]
218 \caption{Unit Attributes by Unit Kind}
219 \label{tab:unitattributesbyunitkind}
220 \begin{tabular}{P{5.5cm}|ccccc}
221 \hline
222                         & \multicolumn{5}{c}{\bfseries Unit Kind} \\
223 \bfseries Attribute     &  Full \&   &  Type  &  Skeleton & Split Full & Split Type \\
224                         & Partial    \\
225 \hline
226 \parbox[c]{3cm}{\DWATlowpc, \DWAThighpc, \DWATranges} \parbox[c]{1cm}{\[ \Biggr\} \]}
227                         & \chkmk  &        &  \chkmk   &        &         \\
228 \hline
229 \DWATname               & \chkmk  &        &           & \chkmk &         \\
230 \DWATlanguage           & \chkmk  & \chkmk &           & \chkmk & \chkmk  \\
231 \DWATstmtlist           & \chkmk  & \chkmk &  \chkmk   &        & \chkmk  \\
232 \hline
233 \DWATmacros             & \chkmk  &        &           & \chkmk &         \\
234 \DWATcompdir            & \chkmk  &        &  \chkmk   &        &         \\
235 \DWATproducer           & \chkmk  &        &           & \chkmk &         \\
236 \DWATidentifiercase     & \chkmk  &        &           & \chkmk &         \\
237 \hline
238 \DWATbasetypes          & \chkmk  &        &           &        &         \\
239 \DWATuseUTFeight        & \chkmk  & \chkmk &  \chkmk   &        & \chkmk  \\
240 \DWATmainsubprogram     & \chkmk  &        &           & \chkmk &         \\
241 \DWATentrypc            & \chkmk  &        &           & \chkmk &         \\
242 \hline
243 \DWATstroffsetsbase     & \chkmk  & \chkmk &  \chkmk   &        &         \\
244 \DWATaddrbase           & \chkmk  &        &  \chkmk   &        &         \\
245 \DWATrangesbase         & \chkmk  &        &  \chkmk   &        &         \\
246 \hline
247 \DWATdwoname            &         &        &  \chkmk   &        &         \\
248 \DWATdwoid              &         &        &  \chkmk   & \chkmk &         \\
249 \hline
250 \end{tabular}
251 \end{table}
252
253
254
255 \needlines{8}
256 The split dwarf object file design depends on having an index of 
257 debugging information available to the consumer. For name lookups, 
258 the consumer can use the \dotdebugnames{} index section (see 
259 Section \refersec{chap:acceleratedaccess}) to 
260 locate a skeleton compilation unit. The
261 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
262 compilation unit can then be used to locate the corresponding
263 DWARF object file for the compilation unit. Similarly, for an
264 address lookup, the consumer can use the \dotdebugaranges{} table,
265 which will also lead to a skeleton compilation unit. For a file
266 and line number lookup, the skeleton compilation units can be
267 used to locate the line number tables.
268
269 \clearpage
270
271 \section{Split DWARF Object File Example}
272 \label{app:splitdwarfobjectfileexample}
273 \addtoindexx{split DWARF object file!example}
274 Consider the example source code in 
275 Figure \refersec{fig:splitobjectexamplesourcefragment1}, 
276 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
277 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
278 When compiled with split DWARF, we will have two DWARF object files,
279 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s}, 
280 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
281
282 \begin{figure}[b]
283 \textit{File demo1.cc}
284 \begin{lstlisting}
285 #include "demo.h"
286
287 bool Box::contains(const Point& p) const
288 {
289     return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
290             p.y() >= ll_.y() && p.y() <= ur_.y());
291 }
292 \end{lstlisting}
293 \caption{Split object example: source fragment \#1}
294 \label{fig:splitobjectexamplesourcefragment1}
295 \end{figure}
296
297 \begin{figure}[h]
298 \textit{File demo2.cc}
299 \begin{lstlisting}
300 #include "demo.h"
301
302 bool Line::clip(const Box& b)
303 {
304   float slope = (end_.y() - start_.y()) / (end_.x() - start_.x());
305   while (1) {
306     // Trivial acceptance.
307     if (b.contains(start_) && b.contains(end_)) return true;
308
309     // Trivial rejection.
310     if (start_.x() < b.l() && end_.x() < b.l()) return false;
311     if (start_.x() > b.r() && end_.x() > b.r()) return false;
312     if (start_.y() < b.b() && end_.y() < b.b()) return false;
313     if (start_.y() > b.t() && end_.y() > b.t()) return false;
314
315     if (b.contains(start_)) {
316       // Swap points so that start_ is outside the clipping 
317       // rectangle.
318       Point temp = start_;
319       start_ = end_;
320       end_ = temp;
321     }
322
323     if (start_.x() < b.l())
324       start_ = Point(b.l(), 
325                      start_.y() + (b.l() - start_.x()) * slope);
326     else if (start_.x() > b.r())
327       start_ = Point(b.r(), 
328                      start_.y() + (b.r() - start_.x()) * slope);
329     else if (start_.y() < b.b())
330       start_ = Point(start_.x() + (b.b() - start_.y()) / slope, 
331                      b.b());
332     else if (start_.y() > b.t())
333       start_ = Point(start_.x() + (b.t() - start_.y()) / slope, 
334                      b.t());
335   }
336 }
337 \end{lstlisting}
338 \caption{Split object example: source fragment \#2}
339 \label{fig:splitobjectexamplesourcefragment2}
340 \end{figure}
341
342 \begin{figure}[h]
343 \textit{File demo.h}
344 \begin{lstlisting}
345 class A {
346   public:
347     Point(float x, float y) : x_(x), y_(y){}
348     float x() const { return x_; }
349     float y() const { return y_; }
350   private:
351     float x_;
352     float y_;
353 };
354
355 class Line {
356   public:
357     Line(Point start, Point end) : start_(start), end_(end){}
358     bool clip(const Box& b);
359     Point start() const { return start_; }
360     Point end() const { return end_; }
361   private:
362     Point start_;
363     Point end_;
364 };
365
366 class Box {
367   public:
368     Box(float l, float r, float b, float t) : ll_(l, b), ur_(r, t){}
369     Box(Point ll, Point ur) : ll_(ll), ur_(ur){}
370     bool contains(const Point& p) const;
371     float l() const { return ll_.x(); }
372     float r() const { return ur_.x(); }
373     float b() const { return ll_.y(); }
374     float t() const { return ur_.y(); }
375   private:
376     Point ll_;
377     Point ur_;
378 };
379
380 \end{lstlisting}
381 \caption{Split object example: source fragment \#3}
382 \label{fig:splitobjectexamplesourcefragment3}
383 \end{figure}
384
385 \clearpage
386 \subsection{Contents of the Object File}
387 The object files each contain the following sections of debug
388 information:
389 \begin{alltt}
390   \dotdebugabbrev
391   \dotdebuginfo
392   \dotdebugranges
393   \dotdebugline
394   \dotdebugstr
395   \dotdebugaddr
396   \dotdebugnames
397   \dotdebugaranges
398 \end{alltt}
399
400 The \dotdebugabbrev{} section contains just a single entry describing
401 the skeleton compilation unit DIE.
402
403 The DWARF description in the \dotdebuginfo{} section 
404 contains just a single DIE, the skeleton compilation unit, 
405 which may look like 
406 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
407
408 \begin{figure}[h]
409 \begin{dwflisting}
410 \begin{alltt}
411
412     \DWTAGcompileunit
413       \DWATcompdir: (reference to directory name in .debug_str)
414       \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
415       \DWATdwoid: 0x44e413b8a2d1b8f
416       \DWATaddrbase: (reference to .debug_addr section)
417       \DWATrangesbase: (reference to range list in .debug_ranges section)
418       \DWATranges: (offset of range list in .debug_ranges section)
419       \DWATstmtlist: (reference to .debug_line section)
420       \DWATlowpc: 0
421       
422 \end{alltt}
423 \end{dwflisting}
424 \caption{Split object example: Skeleton DWARF description}
425 \label{fig:splitdwafexampleskeletondwarfdescription}
426 \end{figure}
427
428 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
429 location of the corresponding \splitDWARFobjectfile{} that
430 contains the full debug information; that file is normally
431 expected to be in the same directory as the object file itself.
432
433 The \DWATdwoid{} attribute provides a hash of the debug
434 information contained in the \splitDWARFobjectfile. This hash serves
435 two purposes: it can be used to verify that the debug information
436 in the \splitDWARFobjectfile{} matches the information in the object
437 file, and it can be used to find the debug information in a DWARF
438 package file.
439
440 \needlines{4}
441 The \DWATaddrbase{} attribute contains the relocatable offset of
442 this object file's contribution to the \dotdebugaddr{} section, and
443 the \DWATrangesbase{} attribute contains the relocatable offset
444 of this object file's contribution to the \dotdebugranges{} section.
445 The \DWATranges{} attribute refers to a specific range list within
446 that contribution, and its value is a (non-relocatable) offset
447 relative to the base. In a compilation unit with a single
448 contiguous range of code, the \DWATranges{} attribute might be
449 omitted, and instead replaced by the pair \DWATlowpc{} and
450 \DWAThighpc.
451
452 The \DWATstmtlist{} attribute contains the relocatable offset of
453 this file's contribution to the \dotdebugline{} table.
454
455 If there is a \DWATranges{} attribute, the \DWATlowpc{} attribute
456 provides a default base address for the range list entries in the
457 \dotdebugranges{} section. It may be omitted if each range list entry
458 provides an explicit base address selection entry; it may provide
459 a relocatable base address, in which case the offsets in each
460 range list entry are relative to it; or it may have the value 0,
461 in which case the offsets in each range list entry are themselves
462 relocatable addresses.
463
464 The \dotdebugranges{} section contains the range list referenced by
465 the \DWATranges{} attribute in the skeleton compilation unit DIE,
466 plus any range lists referenced by \DWATranges{} attributes in the
467 split DWARF object. In our example, \texttt{demo1.o} would contain range
468 list entries for the function \texttt{Box::contains}, as well as for
469 out-of-line copies of the inline functions \texttt{Point::x} and 
470 \texttt{Point::y}.
471
472 The \dotdebugline{} section contains the full line number table for
473 the compiled code in the object file. In the example in
474 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
475 number program header would list the two files, \texttt{demo.h} and
476 \texttt{demo1.cc}, and would contain line number programs for
477 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
478
479 The \dotdebugstr{} section contains the strings referenced indirectly
480 by the compilation unit DIE and by the line number program.
481
482 The \dotdebugaddr{} section contains relocatable addresses of
483 locations in the loadable text and data that are referenced by
484 debugging information entries in the split DWARF object. In the
485 example in \refersec{fig:splitobjectexamplesourcefragment3}, 
486 \texttt{demo1.o} may have three entries:
487 \begin{center}
488 %\footnotesize
489 \begin{tabular}{cl}
490 Slot & Location referenced \\
491 \hline
492    0   &  low PC value for \texttt{Box::contains}  \\
493    1   &  low PC value for \texttt{Point::x}       \\
494    2   &  low PC value for \texttt{Point::y}       \\
495 \end{tabular}
496 \end{center}
497
498 \needlines{4}
499 The \dotdebugnames{}
500 section contains the names defined by the debugging
501 information in the \splitDWARFobjectfile{} 
502 (see Section \refersec{chap:contentsofthenameindex}), 
503 and references the skeleton compilation unit. 
504 When linked together into a final executable,
505 they can be used by a DWARF consumer to lookup a name to find one
506 or more skeleton compilation units that provide information about
507 that name. From the skeleton compilation unit, the consumer can
508 find the \splitDWARFobjectfile{} that it can then read to get the full
509 DWARF information.
510
511 The \dotdebugaranges{} section contains the PC ranges defined in this
512 compilation unit, and allow a DWARF consumer to map a PC value to
513 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
514
515
516 \subsection{Contents of the Split DWARF Object Files}
517 The \splitDWARFobjectfile{s} each contain the following sections:
518 \begin{alltt}
519   \dotdebugabbrevdwo
520   \dotdebuginfodwo{} (for the compilation unit)
521   \dotdebuginfodwo{} (one COMDAT section for each type unit)
522   \dotdebuglocdwo
523   \dotdebuglinedwo
524   \dotdebugmacrodwo
525   \dotdebugstroffsetsdwo
526   \dotdebugstrdwo
527 \end{alltt}
528 The \dotdebugabbrevdwo{} section contains the abbreviation
529 declarations for the debugging information entries in the
530 \dotdebuginfodwo{} section. In general, it looks just like a normal
531 \dotdebugabbrev{} section in a non-split object file.
532
533 The \dotdebuginfodwo{} section containing the compilation unit
534 contains the full debugging information for the compile unit, and
535 looks much like a normal \dotdebuginfo{} section in a non-split
536 object file, with the following exceptions:
537 \begin{itemize}
538 \item The \DWTAGcompileunit{} DIE does not need to repeat the
539 \DWATranges, \DWATlowpc, \DWAThighpc, and
540 \DWATstmtlist{} attributes that are provided in the skeleton
541 compilation unit.
542
543 \item References to strings in the string table use the new form
544 code \DWFORMstrx, referring to slots in the
545 \dotdebugstroffsetsdwo{} section.
546
547 \textit{Use of \DWFORMstrp{} is not appropriate in a \splitDWARFobjectfile.}
548
549 \needlines{4}
550 \item References to range lists in the \dotdebugranges{} section are
551 all relative to the base offset given by \DWATrangesbase{}
552 in the skeleton compilation unit.
553
554 \item References to relocatable addresses in the object file use
555 the new form code \DWFORMaddrx, referring to slots in the
556 \dotdebugaddr{} table, relative to the base offset given by
557 \DWATaddrbase{} in the skeleton compilation unit.
558 \end{itemize}
559
560 Figure \refersec{fig:splitobjectexampledemo1dwodwarfexcerpts} presents
561 some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
562
563 \begin{figure}[h]
564 \figurepart{1}{2}
565 \begin{dwflisting}
566 \begin{alltt}
567
568     \DWTAGcompileunit
569         \DWATproducer [\DWFORMstrx]: (slot 15) (producer string)
570         \DWATlanguage: \DWLANGCplusplus
571         \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
572         \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
573         \DWATdwoid [\DWFORMdataeight]: 0x44e413b8a2d1b8f
574 1$:   \DWTAGclasstype
575           \DWATname [\DWFORMstrx]: (slot 12) "Point"
576           \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
577           \DWATdeclaration: true
578 2$:     \DWTAGsubprogram
579           \DWATexternal: true
580           \DWATname [\DWFORMstrx]: (slot 12) "Point"
581           \DWATdeclfile: 1
582           \DWATdeclline: 5
583           \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff"
584           \DWATaccessibility: \DWACCESSpublic
585           \DWATdeclaration: true
586         ...
587 3$:   \DWTAGclasstype
588           \DWATname [\DWFORMstring]: "Box"
589           \DWATsignature [\DWFORMrefsigeight]: 0xe97a3917c5a6529b
590           \DWATdeclaration: true
591         ...
592 4$:     \DWTAGsubprogram
593             \DWATexternal: true
594             \DWATname [\DWFORMstrx]: (slot 0) "contains"
595             \DWATdeclfile: 1
596             \DWATdeclline: 28
597             \DWATlinkagename [\DWFORMstrx]: (slot 8) "_ZNK3Box8containsERK5Point"
598             \DWATtype: (reference to 7$)
599             \DWATaccessibility: \DWACCESSpublic
600             \DWATdeclaration: true
601         ...
602 \end{alltt}
603 \end{dwflisting}
604 \caption{Split object example: \texttt{demo1.dwo} excerpts}
605 \label{fig:splitobjectexampledemo1dwodwarfexcerpts}
606 \end{figure}
607         
608 \begin{figure}
609 \figurepart{2}{2}
610 \begin{dwflisting}
611 \begin{alltt}
612
613 5$:   \DWTAGsubprogram
614           \DWATspecification: (reference to 4$)
615           \DWATdeclfile: 2
616           \DWATdeclline: 3
617           \DWATlowpc [\DWFORMaddrx]: (slot 0)
618           \DWAThighpc [\DWFORMdataeight]: 0xbb
619           \DWATframebase: \DWOPcallframecfa
620           \DWATobjectpointer: (reference to 6$)
621 6$:     \DWTAGformalparameter
622             \DWATname [\DWFORMstrx]: (slot 13): "this"
623             \DWATtype: (reference to 8$)
624             \DWATartificial: true
625             \DWATlocation: \DWOPfbreg(-24)
626         \DWTAGformalparameter
627             \DWATname [\DWFORMstring]: "p"
628             \DWATdeclfile: 2
629             \DWATdeclline: 3
630             \DWATtype: (reference to 11$)
631             \DWATlocation: \DWOPfbreg(-32)
632       ...
633 7$:   \DWTAGbasetype
634           \DWATbytesize: 1
635           \DWATencoding: \DWATEboolean
636           \DWATname [\DWFORMstrx]: (slot 5) "bool"
637       ...
638 8$:   \DWTAGconsttype
639           \DWATtype: (reference to 9$)
640 9$:   \DWTAGpointertype
641           \DWATbytesize: 8
642           \DWATtype: (reference to 10$)
643 10$:  \DWTAGconsttype
644           \DWATtype: (reference to 3$)
645       ...
646 11$:  \DWTAGconsttype
647           \DWATtype: (reference to 12$)
648 12$:  \DWTAGreferencetype
649           \DWATbytesize: 8
650           \DWATtype: (reference to 13$)
651 13$:  \DWTAGconsttype
652           \DWATtype: (reference to 1$)
653       ...
654 \end{alltt}
655 \end{dwflisting}
656 \begin{center}
657 \vspace{3mm}
658 Figure~\ref{fig:splitobjectexampledemo1dwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
659 \end{center}
660 \end{figure}
661
662 In the defining declaration for \texttt{Box::contains} at 5\$, the
663 \DWATlowpc{} attribute is represented with \DWFORMaddrx,
664 referring to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
665 That slot contains the relocated address of the beginning of the
666 function.
667
668 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
669 section, and looks like a normal type unit in a non-split object,
670 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
671 attribute that refers to a specialized \dotdebuglinedwo{}
672 \addtoindexx{type unit!specialized \texttt{.debug\_line.dwo} section in}
673 \addtoindexx{specialized \texttt{.debug\_line.dwo} section}
674 section. This
675 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 \small
689 %\footnotesize
690 \begin{tabular}{cl|cl}
691     Slot & String & Slot & String \\
692     \hline
693     0  &   contains                         &    10 &   \_ZNK3Box1rEv \\
694     1  &   \_ZNK5Point1xEv                  &    11 &   \_ZN3BoxC4E5PointS0\_ \\
695     2  &   \_ZNK3Box1lEv                    &    12 &   Point\\
696     3  &   \_ZNK3Box1bEv                    &    13 &   this\\
697     4  &   \textit{(compilation directory)} &    14 &   float \\
698     5  &   bool                             &    15 &   \textit{(producer string)} \\
699     6  &   \_ZN3BoxC4Effff                  &    16 &   \_ZN5PointC4Eff \\
700     7  &   demo1.cc                         &    17 &   \_ZNK3Box1tEv \\
701     8  &   \_ZNK3Box8containsERK5Point      & \\
702     9  &   \_ZNK5Point1yEv                  & \\
703 \end{tabular}
704 \end{center}
705 \caption{Split object example: String table slots}
706 \label{fig:splitobjectexamplestringtableslots}
707 \end{figure}
708
709 Each entry in the table is the offset of the string, which is
710 contained in the \dotdebugstrdwo{} section. 
711
712 In a split DWARF object file, all references to
713 strings go through this table (there are no
714 other offsets to \dotdebugstrdwo{} in a split
715 DWARF object file). That is, there
716 is no use of \DWFORMstrp{} in a split DWARF object file.
717
718 The offsets in these slots have no associated relocations, 
719 because they are not part of a relocatable object file.
720
721 When combined into a DWARF package file, however, each 
722 slot must be adjusted to refer to the appropriate offset 
723 within the merged string table (\dotdebugstrdwo{}).
724 The tool that builds the DWARF package file must understand 
725 the structure of the \dotdebugstroffsetsdwo{} section in 
726 order to apply the necessary adjustments. 
727 (See Section \refersec{app:dwarfpackagefileexample} 
728 for an example of a DWARF package file.)
729
730 \needlines{4}
731 The \dotdebuglocdwo{} section contains the location lists referenced
732 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
733 section has a similar format to the \dotdebugloc{} section in a
734 non-split object, but it has some small differences as explained
735 in Section \refersec{datarep:locationlistentriesinsplitobjects}. 
736 In \texttt{demo2.dwo} as shown in 
737 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}, 
738 the debugging information for \texttt{Line::clip} describes a local 
739 variable \texttt{slope} whose location varies based on the PC.
740 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts} 
741 presents some excerpts from the \dotdebuginfodwo{} section for 
742 \texttt{demo2.dwo}.
743
744 \begin{figure}[b]
745 \figurepart{1}{2}
746 \begin{dwflisting}
747 \begin{alltt}
748
749 1$: \DWTAGclasstype
750         \DWATname [\DWFORMstrx]: (slot 20) "Line"
751         \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
752         \DWATdeclaration: true
753     ...
754 2$:   \DWTAGsubprogram
755           \DWATexternal: true
756           \DWATname [\DWFORMstrx]: (slot 19) "clip"
757           \DWATdeclfile: 2
758           \DWATdeclline: 16
759           \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
760           \DWATtype: (reference to DIE for bool)
761           \DWATaccessibility: \DWACCESSpublic
762           \DWATdeclaration: true
763       ...
764 \end{alltt}
765 \end{dwflisting}
766 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
767 \label{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}
768 \end{figure}
769
770 \begin{figure}
771 \figurepart{2}{2}
772 \begin{dwflisting}
773 \begin{alltt}
774
775 3$:   \DWTAGsubprogram
776           \DWATspecification: (reference to 2$)
777           \DWATdeclfile: 1
778           \DWATdeclline: 3
779           \DWATlowpc [\DWFORMaddrx]: (slot 32)
780           \DWAThighpc [\DWFORMdataeight]: 0x1ec
781           \DWATframebase: \DWOPcallframecfa
782           \DWATobjectpointer: (reference to 4$)
783 4$:     \DWTAGformalparameter
784             \DWATname: (indexed string: 0x11): this
785             \DWATtype: (reference to DIE for type const Point* const)
786             \DWATartificial: 1
787             \DWATlocation: 0x0 (location list)
788 5$:     \DWTAGformalparameter
789             \DWATname: b
790             \DWATdeclfile: 1
791             \DWATdeclline: 3
792             \DWATtype: (reference to DIE for type const Box& const)
793             \DWATlocation [\DWFORMsecoffset]: 0x2a
794 6$:     \DWTAGlexicalblock
795             \DWATlowpc [\DWFORMaddrx]: (slot 17)
796             \DWAThighpc: 0x1d5
797 7$:       \DWTAGvariable
798               \DWATname [\DWFORMstrx]: (slot 28): "slope"
799               \DWATdeclfile: 1
800               \DWATdeclline: 5
801               \DWATtype: (reference to DIE for type float)
802               \DWATlocation [\DWFORMsecoffset]: 0x49
803
804 \end{alltt}
805 \end{dwflisting}
806 \begin{center}
807 \vspace{3mm}
808 Figure~\ref{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
809 \end{center}
810 \end{figure}
811
812 In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts},
813 The \DWTAGformalparameter{} entries at \texttt{4\$} and \texttt{5\$} refer to the
814 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
815 \DWTAGvariable{} entry for \texttt{slope} at \texttt{7\$} refers to the location
816 list at offset \texttt{0x49}. 
817 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
818 shows a representation of the
819 location lists at those offsets in the \dotdebuglocdwo{} section.
820
821 \begin{figure}
822 \begin{dwflisting}
823 \begin{tabular}{rlrrl}
824 \texttt{offset} & entry type & start & length & expression \\
825 \hline \\
826 0x00 & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfive~(rdi) \\
827 0x09 & \DWLLEstartlengthentry & [11] & 0x01b9 & \DWOPregthree~(rbx) \\
828 0x12 & \DWLLEstartlengthentry & [29] & 0x0003 & \DWOPbregtwelve~(r12):\\
829 &&&& -8; \DWOPstackvalue \\
830 0x1d & \DWLLEstartlengthentry & [31] & 0x0001 & \DWOPentryvalue: \\
831 &&&& (\DWOPregfive~(rdi)); \\
832 &&&& \DWOPstackvalue \\
833 0x29 & \DWLLEendoflistentry &&& \\
834 \\   & \hhline{-} &&& \\
835 0x2a & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfour~(rsi)) \\
836 0x33 & \DWLLEstartlengthentry & [11] & 0x01ba & \DWOPregsix~(rbp)) \\
837 0x3c & \DWLLEstartlengthentry & [30] & 0x0003 & \DWOPentryvalue: \\
838 &&&& (\DWOPregfour~(rsi)); \\
839 &&&& \DWOPstackvalue \\
840 0x48 & \DWLLEendoflistentry &&& \\
841 \\   & \hhline{-} &&& \\
842 0x49 & \DWLLEstartlengthentry & [10] & 0x0004 & \DWOPregeighteen~(xmm1) \\
843 0x52 & \DWLLEstartlengthentry & [11] & 0x01bd & \DWOPfbreg: -36 \\
844 0x5c & \DWLLEendoflistentry &&& \\
845 &&&& \\
846 \end{tabular}
847 \end{dwflisting}
848 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
849 \label{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
850 \end{figure}
851
852 In each \DWLLEstartlengthentry{}, the start field is the index
853 of a slot in the \dotdebugaddr{} section, relative to the base
854 offset defined by the compilations unit's \DWATaddrbase{}
855 attribute. The \dotdebugaddr{} slots referenced by these entries give
856 the relocated address of a label within the function where the
857 address range begins. The length field gives the length of the
858 address range.
859
860 \clearpage
861 \section{DWARF Package File Example}
862 \label{app:dwarfpackagefileexample}
863 \addtoindexx{DWARF duplicate elimination!examples}
864
865 \bb
866 A \definitionx{DWARF package file} is a collection of split 
867 DWARF object files.
868 In general, it will be much smaller than the sum of the split
869 DWARF object files, because the packaging process removes duplicate
870 type units and merges the string tables. Aside from those two
871 optimizations, however, each compilation unit and each type unit
872 from a split DWARF object file is copied verbatim into the package
873 file.
874
875 The package file contains the same set of sections as a split
876 DWARF object file, plus two additional sections described below.
877
878 The packaging utility, like a linker, combines sections of the
879 same name by concatenation. While a split DWARF object may
880 contain multiple \dotdebuginfodwo{} sections, one for the
881 compilation unit, and one for each type unit, a package file
882 contains a single \dotdebuginfodwo{} section. The combined
883 \dotdebuginfodwo{} section contains each compilation unit and one
884 copy of each type unit (discarding any duplicate type
885 signatures).
886
887 As part of merging the string tables, the packaging utility
888 treats the \dotdebugstrdwo{} and \dotdebugstroffsetsdwo{}
889 sections specially. Rather than
890 combining them by simple concatenation, it instead builds a new
891 string table consisting of the unique strings from each input
892 string table. Because all references to these strings use the
893 \DWFORMstrx{} form, the packaging utility only needs to adjust the
894 string offsets in each \dotdebugstroffsetsdwo{} contribution after
895 building the new \dotdebugstrdwo{} section.
896
897 Each compilation unit or type unit consists of a set of
898 inter-related contributions to each section in the package file.
899 For example, a compilation unit may have contributions in
900 \dotdebuginfodwo{}, \dotdebugabbrevdwo{}, \dotdebuglinedwo{},
901 \dotdebugstroffsetsdwo{}, and so on. In order to maintain the ability 
902 for a consumer to follow references between these sections, the
903 package file contains two additional sections: a compilation unit
904 (CU) index, and a type unit (TU) index. These indexes allow a
905 consumer to look up a compilation unit (by its \CUsignature) or 
906 a type unit (by its \TUsignature), and locate each contribution 
907 that belongs to that unit.
908
909 As an example, consider a package file, \texttt{demo.dwp}, formed by
910 combining \texttt{demo1.dwo} and \texttt{demo2.dwo} from the previous example
911 (see Appendix \refersec{app:splitdwarfobjectfileexample}). The
912 resulting package file would contain the sections shown in Table
913 \refersec{fig:sectionsandcontributionsinapackagefile}, 
914 with contributions from each input file as shown.
915
916 \begin{table}[h]
917 \caption{Sections and contributions in a package file}
918 \label{fig:sectionsandcontributionsinapackagefile}
919 \begin{center}
920 \begin{tabular}{P{4.7cm}|P{8cm}}
921 \hline
922 \bfseries Target \texttt{.dwp} section & \bfseries Source of section contributions \\
923 \hline
924   \dotdebugabbrevdwo{}
925 &    \dotdebugabbrevdwo{} from \texttt{demo1.dwo} \newline
926      \dotdebugabbrevdwo{} from \texttt{demo2.dwo} \\
927 \hline \newline
928   \dotdebuginfodwo{} \newline (for the compilation units and type units)
929 &    compilation unit from \texttt{demo1.dwo} \newline
930      compilation unit from \texttt{demo2.dwo} \newline
931      type unit for class \texttt{Box} from \texttt{demo1.dwo}   \newline
932      type unit for class \texttt{Point} from \texttt{demo1.dwo} \newline
933      type unit for class \texttt{Line} from \texttt{demo2.dwo}  \\
934 \hline
935   \dotdebuglocdwo{}
936 &    \dotdebuglocdwo{} from \texttt{demo1.dwo} \newline
937      \dotdebuglocdwo{} from \texttt{demo2.dwo} \\
938 \hline
939   \dotdebuglinedwo{}
940 &    \dotdebuglinedwo{} from \texttt{demo1.dwo} \newline
941      \dotdebuglinedwo{} from \texttt{demo2.dwo} \\
942 \hline
943   \dotdebugstroffsetsdwo{}
944 &    \dotdebugstroffsetsdwo{} from \texttt{demo1.dwo}, \hspace*{6mm}adjusted \newline
945      \dotdebugstroffsetsdwo{} from \texttt{demo2.dwo}, \hspace*{6mm}adjusted \\
946 \hline
947   \dotdebugstrdwo{}
948 &    new merged string table \\
949 \hline
950   \dotdebugcuindex
951 &    new CU index \\
952 \hline
953   \dotdebugtuindex
954 &    new TU index \\
955 \hline
956 \end{tabular}
957 \end{center}
958 \end{table}
959
960 \needlines{4}
961 The \dotdebugabbrevdwo{}, \dotdebuglocdwo{} and \dotdebuglinedwo{}
962 sections have been copied over from the two \texttt{.dwo} files as
963 individual contributions to the corresponding sections in the
964 \texttt{.dwp} file. A record of the offset of each contribution within 
965 the combined section, and the size of each contribution is recorded
966 as part of the CU and TU index sections.
967
968 The \dotdebuginfodwo{} sections corresponding to each compilation
969 unit have been copied as individual contributions to the combined
970 \dotdebuginfodwo{} section, and one copy of each type unit has also
971 been copied. The type units for class \texttt{Box} and class 
972 \texttt{Point}, for example, are contained in both \texttt{demo1.dwo} 
973 and \texttt{demo2.dwo}, but only one instance of each is copied into 
974 the package file.
975
976 The \dotdebugstrdwo{} sections from each file have been merged to
977 form a new string table with no duplicates, requiring the
978 adjustment of all references to those strings. The
979 \dotdebugstroffsetsdwo{} sections from the \texttt{.dwo} files have 
980 been copied as individual contributions, but the string table offset
981 in each slot of those contributions has been adjusted to point to
982 the correct offset in the merged string table.
983
984 The \dotdebugcuindex{} and \dotdebugtuindex{} sections provide a
985 directory to these contributions. 
986 Table \referfol{fig:examplecuindexsection} shows an example CU
987 index section containing the two compilation units from 
988 \texttt{demo1.dwo} and \texttt{demo2.dwo}. The CU index shows that 
989 for the compilation unit from \texttt{demo1.dwo}, with \CUsignature{} 
990 \texttt{0x044e413b8a2d1b8f}, its contribution to the \dotdebuginfodwo{} 
991 section begins at offset 0, and is 325 bytes long. For the compilation 
992 unit from \texttt{demo2.dwo}, with \CUsignature{} 
993 \texttt{0xb5f0ecf455e7e97e}, its contribution to the \dotdebuginfodwo{}
994 section begins at offset 325, and is 673 bytes long.
995
996 Likewise, we can find the contributions to the related sections.
997 In Figure \referfol{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}, 
998 we see that the \DWTAGvariable{} DIE at \texttt{7\$} has a
999 reference to a location list at offset 0x49 (decimal 73). Because
1000 this is part of the compilation unit for \texttt{demo2.dwo}, with 
1001 unit signature \texttt{0xb5f0ecf455e7e97e}, we see that its contribution 
1002 to \dotdebuglocdwo{} begins at offset 84, so the location list from
1003 Figure F.8 can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
1004 the combined \dotdebuglocdwo{} section.
1005
1006 \begin{table}[h]
1007 \caption{Example CU index section}
1008 \label{fig:examplecuindexsection}
1009 \begin{center}
1010 \begin{tabular}{lrrrrrr}
1011 \hline \\
1012   \multicolumn{2}{l}{Version:}&                 5 &&&&\\
1013   \multicolumn{2}{l}{Number of columns:}&       5 &&&&\\
1014   \multicolumn{2}{l}{Number of used entries:}&  2 &&&&\\
1015   \multicolumn{2}{l}{Number of slots:}&         16 &&&&\\
1016 \\
1017   \multicolumn{7}{c}{Offset table} \\
1018   \hline
1019   slot&  signature&             info&   abbrev&      loc&     line& str\_off \\
1020     14& \texttt{0xb5f0ecf455e7e97e}&      325&      452&       84&       52&       72 \\
1021     15& \texttt{0x044e413b8a2d1b8f}&        0&        0&        0&        0&        0 \\
1022 \\
1023   \multicolumn{7}{c}{Size table} \\
1024   \hline
1025   slot&                    &     info&   abbrev&      loc&     line& str\_off \\
1026     14&                    &      673&      593&       93&       52&      120 \\
1027     15&                    &      325&      452&       84&       52&       72 \\
1028 \\ \hline 
1029 \end{tabular}
1030 \end{center}
1031 \end{table}
1032
1033 \needlines{4}
1034 Table \referfol{fig:exampletuindexsection} 
1035 shows an example TU index section containing the
1036 three type units for classes \texttt{Box}, \texttt{Point}, and 
1037 \texttt{Line}. Each type unit
1038 contains contributions from \dotdebuginfodwo{}, \dotdebugabbrevdwo{},
1039 \dotdebuglinedwo{} and \dotdebugstroffsetsdwo{}. In this example, the
1040 type units for classes \texttt{Box} and \texttt{Point} come from 
1041 \texttt{demo1.dwo}, and
1042 share the abbreviations table, line number table, and string
1043 offsets table with the compilation unit from \texttt{demo1.dwo}. 
1044 Likewise, the type unit for class \texttt{Line} shares tables 
1045 from \texttt{demo2.dwo}. (The
1046 sharing of these tables between compilation units and type units
1047 is typical for some implementations, but is not required by the
1048 DWARF standard.)
1049
1050 \begin{table}[h]
1051 \caption{Example TU index section}
1052 \label{fig:exampletuindexsection}
1053 \begin{center}
1054 \begin{tabular}{lrrrrr}
1055 \hline
1056   \multicolumn{2}{l}{Version:}&                 5 \\
1057   \multicolumn{2}{l}{Number of columns:}&       4 \\
1058   \multicolumn{2}{l}{Number of used entries:}&  3 \\
1059   \multicolumn{2}{l}{Number of slots:}&         32 \\
1060 \\
1061   \multicolumn{6}{c}{Offset table} \\
1062   \hline
1063   slot&  signature&                    info&   abbrev&     line& str\_off \\
1064   11& \texttt{0x2f33248f03ff18ab}&     1321&        0&        0&        0 \\
1065   17& \texttt{0x79c7ef0eae7375d1}&     1488&      452&       52&       72 \\
1066   27& \texttt{0xe97a3917c5a6529b}&      998&        0&        0&        0 \\
1067 \\
1068   \multicolumn{6}{c}{Size table} \\
1069   \hline
1070   slot&                          &     info&   abbrev&     line& str\_off \\
1071   11&                            &     167&      452&       52&       72 \\
1072   17&                            &     217&      593&       52&      120 \\
1073   27&                            &     323&      452&       52&       72 \\
1074 \\
1075 \hline
1076 \end{tabular}
1077 \end{center}
1078 \end{table}
1079
1080 \eb