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