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
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.
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
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.
47 The optional set of debugging sections includes the following:
50 \dotdebugabbrevdwo{} - Contains the abbreviations table(s) used by
51 the \dotdebuginfodwo{} section.
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.
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.
65 \dotdebugstrdwo{} - Contains the string table for all indirect
66 strings referenced by the debugging information in the
67 \dotdebuginfodwo{} sections.
69 \dotdebugstroffsetsdwo{} - Contains the string offsets table
70 for the strings in the \dotdebugstrdwo{}{} section.
72 \dotdebugmacrodwo{} - Contains macro definition information,
73 normally found in the \dotdebugmacro{} section.
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
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).
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).
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{}
111 The debug sections that continue to be linked into the
112 output binary include the following:
115 \dotdebugabbrev{} - Contains the abbreviation codes used by the
116 skeleton \dotdebuginfo{} section.
118 \dotdebugaddr{} - Contains references to loadable sections,
119 indexed by attributes of form \DWFORMaddrx{} or location
121 \DWOPaddrx{} opcodes.
123 \dotdebugaranges{} - Contains the accelerated range lookup table
124 for the compilation unit.
126 \dotdebugframe{} - Contains the frame tables.
128 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
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
139 \dotdebuglinestr{} - Contains strings for file names used in
140 combination with the \dotdebugline{} section.
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.
148 \dotdebugranges{} - Contains the range lists.
150 \dotdebugstr{} - Contains any strings referenced by the skeleton
151 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
153 \dotdebugstroffsets{} - Contains the string offsets table for
154 the strings in the \dotdebugstr{} section (if form \DWFORMstrx{} is used).
158 The skeleton \DWTAGcompileunit{} DIE
159 may have the following attributes:
160 \autocols[0pt]{c}{3}{l}{
170 \DWATstroffsetsbase{}
173 All other attributes of the compilation unit DIE are moved to
174 the full DIE in the \dotdebuginfodwo{} section.
177 The \HFNdwoid{} field is present in headers of the skeleton DIE
178 and the header of the full DIE, so that a consumer
183 Relocations are neither necessary nor useful in
184 \texttt{.dwo} files, because the \texttt{.dwo}
185 files contain only debugging information that does not need to be
186 processed by a linker. Relocations are rendered unnecessary via
189 \begin{enumerate}[1. ]
190 \item Some values needing relocation are kept in the \texttt{.o} file
191 (for example, references to the line number program from the skeleton
194 \item Some values do not need a relocation because they refer from
195 one \dotdwo{} section to another \dotdwo{} section
196 in the same compilation unit.
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).
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).
211 Table \refersec{tab:unitattributesbyunitkind} summarizes which
212 attributes are defined for use in the various
213 kinds of compilation units (see Section \refersec{chap:unitentries}).
214 It compares and contrasts both conventional and split object-related
218 \caption{Unit attributes by unit kind}
219 \label{tab:unitattributesbyunitkind}
220 \begin{tabular}{P{5.5cm}|cc|ccc}
222 & \multicolumn{5}{c}{\bfseries Unit Kind} \\
223 & \multicolumn{2}{c}{\bfseries Conventional}
224 & \multicolumn{3}{c}{\bfseries Skeleton and Split} \\
225 \bfseries Attribute & Full \& & Type & Skeleton & Split Full & Split Type \\
228 \DWATaddrbase & \chkmk & & \chkmk & & \\
230 \DWATbasetypes & \chkmk & & & & \\
232 \DWATcompdir & \chkmk & & \chkmk & & \\
234 \bbeb %\DWATdwoid & & & \chkmk & \chkmk & \\
236 \DWATdwoname & & & \chkmk & & \\
238 \DWATentrypc & \chkmk & & & \chkmk & \\
240 \DWAThighpc & \chkmk & & \chkmk & & \\
242 \DWATidentifiercase & \chkmk & & & \chkmk & \\
244 \DWATlanguage & \chkmk & \chkmk & & \chkmk & \chkmk \\
246 \DWATlowpc & \chkmk & & \chkmk & & \\
248 \DWATmacros & \chkmk & & & \chkmk & \\
250 \DWATmainsubprogram & \chkmk & & & \chkmk & \\
252 \DWATname & \chkmk & & & \chkmk & \\
254 \DWATproducer & \chkmk & & & \chkmk & \\
256 \DWATranges & \chkmk & & \chkmk & & \\
258 \DWATrangesbase & \chkmk & & \chkmk & & \\
260 \DWATstmtlist & \chkmk & \chkmk & \chkmk & & \chkmk \\
262 \DWATstroffsetsbase & \chkmk & \chkmk & \chkmk & & \\
264 \DWATuseUTFeight & \chkmk & \chkmk & \chkmk & \chkmk & \chkmk \\
270 The split dwarf object file design depends on having an index of
271 debugging information available to the consumer. For name lookups,
272 the consumer can use the \dotdebugnames{} index section (see
273 Section \refersec{chap:acceleratedaccess}) to
274 locate a skeleton compilation unit. The
275 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
276 compilation unit can then be used to locate the corresponding
277 DWARF object file for the compilation unit. Similarly, for an
278 address lookup, the consumer can use the \dotdebugaranges{} table,
279 which will also lead to a skeleton compilation unit. For a file
280 and line number lookup, the skeleton compilation units can be
281 used to locate the line number tables.
285 \section{Split DWARF Object File Example}
286 \label{app:splitdwarfobjectfileexample}
287 \addtoindexx{split DWARF object file!example}
288 Consider the example source code in
289 Figure \refersec{fig:splitobjectexamplesourcefragment1},
290 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
291 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
292 When compiled with split DWARF, we will have two DWARF object files,
293 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s},
294 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
298 \textit{File demo1.cc}
302 bool Box::contains(const Point& p) const
304 return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
305 p.y() >= ll_.y() && p.y() <= ur_.y());
308 \caption{Split object example: source fragment \#1}
309 \label{fig:splitobjectexamplesourcefragment1}
313 \textit{File demo2.cc}
317 bool Line::clip(const Box& b)
319 float slope = (end_.y() - start_.y()) / (end_.x() - start_.x());
321 // Trivial acceptance.
322 if (b.contains(start_) && b.contains(end_)) return true;
324 // Trivial rejection.
325 if (start_.x() < b.l() && end_.x() < b.l()) return false;
326 if (start_.x() > b.r() && end_.x() > b.r()) return false;
327 if (start_.y() < b.b() && end_.y() < b.b()) return false;
328 if (start_.y() > b.t() && end_.y() > b.t()) return false;
330 if (b.contains(start_)) {
331 // Swap points so that start_ is outside the clipping
338 if (start_.x() < b.l())
339 start_ = Point(b.l(),
340 start_.y() + (b.l() - start_.x()) * slope);
341 else if (start_.x() > b.r())
342 start_ = Point(b.r(),
343 start_.y() + (b.r() - start_.x()) * slope);
344 else if (start_.y() < b.b())
345 start_ = Point(start_.x() + (b.b() - start_.y()) / slope,
347 else if (start_.y() > b.t())
348 start_ = Point(start_.x() + (b.t() - start_.y()) / slope,
353 \caption{Split object example: source fragment \#2}
354 \label{fig:splitobjectexamplesourcefragment2}
362 Point(float x, float y) : x_(x), y_(y){}
363 float x() const { return x_; }
364 float y() const { return y_; }
372 Line(Point start, Point end) : start_(start), end_(end){}
373 bool clip(const Box& b);
374 Point start() const { return start_; }
375 Point end() const { return end_; }
383 Box(float l, float r, float b, float t) : ll_(l, b), ur_(r, t){}
384 Box(Point ll, Point ur) : ll_(ll), ur_(ur){}
385 bool contains(const Point& p) const;
386 float l() const { return ll_.x(); }
387 float r() const { return ur_.x(); }
388 float b() const { return ll_.y(); }
389 float t() const { return ur_.y(); }
396 \caption{Split object example: source fragment \#3}
397 \label{fig:splitobjectexamplesourcefragment3}
401 \subsection{Contents of the Object File}
402 The object files each contain the following sections of debug
415 The \dotdebugabbrev{} section contains just a single entry describing
416 the skeleton compilation unit DIE.
418 The DWARF description in the \dotdebuginfo{} section
419 contains just a single DIE, the skeleton compilation unit,
421 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
428 \DWATcompdir: (reference to directory name in .debug_str)
429 \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
430 \DWATaddrbase: (reference to .debug_addr section)
431 \DWATrangesbase: (reference to range list in .debug_ranges section)
432 \DWATranges: (offset of range list in .debug_ranges section)
433 \DWATstmtlist: (reference to .debug_line section)
438 \caption{Split object example: Skeleton DWARF description}
439 \label{fig:splitdwafexampleskeletondwarfdescription}
442 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
443 location of the corresponding \splitDWARFobjectfile{} that
444 contains the full debug information; that file is normally
445 expected to be in the same directory as the object file itself.
449 \HFNdwoid{} field in the header of the skeleton unit provides
450 an ID or key for the debug information contained in the
451 DWARF object file. This ID serves
453 two purposes: it can be used to verify that the debug information
454 in the \splitDWARFobjectfile{} matches the information in the object
455 file, and it can be used to find the debug information in a DWARF
459 The \DWATaddrbase{} attribute contains the relocatable offset of
460 this object file's contribution to the \dotdebugaddr{} section, and
461 the \DWATrangesbase{} attribute contains the relocatable offset
462 of this object file's contribution to the \dotdebugranges{} section.
463 The \DWATranges{} attribute refers to a specific range list within
464 that contribution, and its value is a (non-relocatable) offset
465 relative to the base. In a compilation unit with a single
466 contiguous range of code, the \DWATranges{} attribute might be
467 omitted, and instead replaced by the pair \DWATlowpc{} and
470 The \DWATstmtlist{} attribute contains the relocatable offset of
471 this file's contribution to the \dotdebugline{} table.
473 There is both a \DWATranges{} attribute as well as a \DWATlowpc{}
475 provides a default base address for the range list entries in the
476 \dotdebugranges{} section.
478 The \dotdebugranges{} section contains the range list referenced by
479 the \DWATranges{} attribute in the skeleton compilation unit DIE,
480 plus any range lists referenced by \DWATranges{} attributes in the
481 split DWARF object. In this example, \texttt{demo1.o} contains range
482 list entries for the function \texttt{Box::contains}, as well as for
483 out-of-line copies of the inline functions \texttt{Point::x} and
486 The \dotdebugline{} section contains the full line number table for
487 the compiled code in the object file. As shown in
488 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
489 number program header lists the two file names, \texttt{demo.h} and
490 \texttt{demo1.cc}, and contains line number programs for
491 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
493 The \dotdebugstr{} section contains the strings referenced indirectly
494 by the compilation unit DIE and by the line number program.
496 The \dotdebugaddr{} section contains relocatable addresses of
497 locations in the loadable text and data that are referenced by
498 debugging information entries in the split DWARF object. In the
499 example in \refersec{fig:splitobjectexamplesourcefragment3},
500 \texttt{demo1.o} may have three entries:
504 Slot & Location referenced \\
506 0 & low PC value for \texttt{Box::contains} \\
507 1 & low PC value for \texttt{Point::x} \\
508 2 & low PC value for \texttt{Point::y} \\
514 section contains the names defined by the debugging
515 information in the \splitDWARFobjectfile{}
516 (see Section \refersec{chap:contentsofthenameindex}),
517 and references the skeleton compilation unit.
518 When linked together into a final executable,
519 they can be used by a DWARF consumer to lookup a name to find one
520 or more skeleton compilation units that provide information about
521 that name. From the skeleton compilation unit, the consumer can
522 find the \splitDWARFobjectfile{} that it can then read to get the full
525 The \dotdebugaranges{} section contains the PC ranges defined in this
526 compilation unit, and allow a DWARF consumer to map a PC value to
527 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
530 \subsection{Contents of the Split DWARF Object Files}
531 The \splitDWARFobjectfile{s} each contain the following sections:
534 \dotdebuginfodwo{} (for the compilation unit)
535 \dotdebuginfodwo{} (one COMDAT section for each type unit)
539 \dotdebugstroffsetsdwo
542 The \dotdebugabbrevdwo{} section contains the abbreviation
543 declarations for the debugging information entries in the
544 \dotdebuginfodwo{} section.
546 The \dotdebuginfodwo{} section containing the compilation unit
547 contains the full debugging information for the compile unit, and
548 looks much like a normal \dotdebuginfo{} section in a non-split
549 object file, with the following exceptions:
551 \item The \DWTAGcompileunit{} DIE does not need to repeat the
552 \DWATranges, \DWATlowpc, \DWAThighpc, and
553 \DWATstmtlist{} attributes that are provided in the skeleton
556 \item References to strings in the string table use the
557 form code \DWFORMstrx, referring to slots in the
558 \dotdebugstroffsetsdwo{} section.
560 \item References to range lists in the \dotdebugranges{} section are
561 all relative to the base offset given by \DWATrangesbase{}
562 in the skeleton compilation unit.
565 \item References to relocatable addresses in the object file
566 use the form code \DWFORMaddrx, referring to slots in the
567 \dotdebugaddr{} table, relative to the base offset given by
568 \DWATaddrbase{} in the skeleton compilation unit.
572 Figure \referfol{fig:splitobjectexampledemoonedwodwarfexcerpts} presents
573 excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
582 \DWATproducer [\DWFORMstrx]: (slot 15) (producer string)
583 \DWATlanguage: \DWLANGCplusplus
584 \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
585 \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
587 \DWATname [\DWFORMstrx]: (slot 12) "Point"
588 \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
589 \DWATdeclaration: true
592 \DWATname [\DWFORMstrx]: (slot 12) "Point"
595 \DWATlinkagename [\DWFORMstrx]: (slot 16) "_ZN5PointC4Eff"
596 \DWATaccessibility: \DWACCESSpublic
597 \DWATdeclaration: true
600 \DWATname [\DWFORMstring]: "Box"
601 \DWATsignature [\DWFORMrefsigeight{}]: 0xe97a3917c5a6529b
602 \DWATdeclaration: true
606 \DWATname [\DWFORMstrx]: (slot 0) "contains"
609 \DWATlinkagename [\DWFORMstrx: (slot 8)
610 "_ZNK3Box8containsERK5Point"
611 \DWATtype: (reference to 7$)
612 \DWATaccessibility: \DWACCESSpublic
613 \DWATdeclaration: true
618 \caption{Split object example: \texttt{demo1.dwo} excerpts}
619 \label{fig:splitobjectexampledemoonedwodwarfexcerpts}
628 \DWATspecification: (reference to 4$)
631 \DWATlowpc [\DWFORMaddrx]: (slot 0)
632 \DWAThighpc [\DWFORMdataeight]: 0xbb
633 \DWATframebase: \DWOPcallframecfa
634 \DWATobjectpointer: (reference to 6$)
635 6$: \DWTAGformalparameter
636 \DWATname [\DWFORMstrx]: (slot 13): "this"
637 \DWATtype: (reference to 8$)
638 \DWATartificial: true
639 \DWATlocation: \DWOPfbreg(-24)
640 \DWTAGformalparameter
641 \DWATname [\DWFORMstring]: "p"
644 \DWATtype: (reference to 11$)
645 \DWATlocation: \DWOPfbreg(-32)
649 \DWATencoding: \DWATEboolean
650 \DWATname [\DWFORMstrx]: (slot 5) "bool"
653 \DWATtype: (reference to 9$)
654 9$: \DWTAGpointertype
656 \DWATtype: (reference to 10$)
658 \DWATtype: (reference to 3$)
661 \DWATtype: (reference to 12$)
662 12$: \DWTAGreferencetype
664 \DWATtype: (reference to 13$)
666 \DWATtype: (reference to 1$)
672 Figure~\ref{fig:splitobjectexampledemoonedwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
677 In the defining declaration for \texttt{Box::contains} at 5\$, the
678 \DWATlowpc{} attribute is represented with \DWFORMaddrx,
679 referring to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
680 That slot contains the relocated address of the beginning of the
683 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
684 section, and looks like a normal type unit in a non-split object,
685 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
686 attribute that refers to a specialized \dotdebuglinedwo{}
687 \addtoindexx{type unit!specialized \texttt{.debug\_line.dwo} section in}
688 \addtoindexx{specialized \texttt{.debug\_line.dwo} section}
690 section contains a normal line number
691 program header with a list of include directories and filenames,
692 but no line number program. This section is used only as a
693 reference for filenames needed for \DWATdeclfile{} attributes
694 within the type unit.
696 The \dotdebugstroffsetsdwo{} section contains an entry for each
697 unique string in the string table.
698 Each entry in the table is the offset of the string, which is
699 contained in the \dotdebugstrdwo{} section.
701 In a split DWARF object file, all references to
702 strings go through this table (there are no
703 other offsets to \dotdebugstrdwo{} in a split
704 DWARF object file). That is, there
705 is no use of \DWFORMstrp{} in a split DWARF object file.
707 The offsets in these slots have no associated relocations,
708 because they are not part of a relocatable object file.
711 When combined into a DWARF package file, however, each
712 slot must be adjusted to refer to the appropriate offset
713 within the merged string table (\dotdebugstrdwo{}).
714 The tool that builds the DWARF package file must understand
715 the structure of the \dotdebugstroffsetsdwo{} section in
716 order to apply the necessary adjustments.
717 Section \refersec{app:dwarfpackagefileexample} presents
718 an example of a DWARF package file.
721 The \dotdebuglocdwo{} section contains the location lists referenced
722 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
723 section has a similar format to the \dotdebugloc{} section in a
724 non-split object, but it has some small differences as explained
725 in Section \refersec{datarep:locationlistentriesinsplitobjects}.
733 \DWATname [\DWFORMstrx]: (slot 20) "Line"
734 \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
735 \DWATdeclaration: true
739 \DWATname [\DWFORMstrx]: (slot 19) "clip"
742 \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
743 \DWATtype: (reference to DIE for bool)
744 \DWATaccessibility: \DWACCESSpublic
745 \DWATdeclaration: true
750 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
751 \label{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts}
760 \DWATspecification: (reference to 2$)
763 \DWATlowpc [\DWFORMaddrx]: (slot 32)
764 \DWAThighpc [\DWFORMdataeight]: 0x1ec
765 \DWATframebase: \DWOPcallframecfa
766 \DWATobjectpointer: (reference to 4$)
767 4$: \DWTAGformalparameter
768 \DWATname: (indexed string: 0x11): this
769 \DWATtype: (reference to DIE for type const Point* const)
771 \DWATlocation: 0x0 (location list)
772 5$: \DWTAGformalparameter
776 \DWATtype: (reference to DIE for type const Box& const)
777 \DWATlocation [\DWFORMsecoffset]: 0x2a
778 6$: \DWTAGlexicalblock
779 \DWATlowpc [\DWFORMaddrx]: (slot 17)
782 \DWATname [\DWFORMstrx]: (slot 28): "slope"
785 \DWATtype: (reference to DIE for type float)
786 \DWATlocation [\DWFORMsecoffset]: 0x49
792 Figure~\ref{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
797 In \texttt{demo2.dwo} as shown in
798 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts},
799 the debugging information for \texttt{Line::clip}
800 starting at \texttt{2\$} describes a local
801 variable \texttt{slope} at \texttt{7\$}
802 whose location varies based on the PC.
803 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
804 presents some excerpts from the \dotdebuginfodwo{} section for
809 In Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts},
810 the \DWTAGformalparameter{} entries at \texttt{4\$} and \texttt{5\$} refer to the
811 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
812 \DWTAGvariable{} entry for \texttt{slope}
813 refers to the location list at offset \texttt{0x49}.
814 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
815 shows a representation of the
816 location lists at those offsets in the \dotdebuglocdwo{} section.
818 % Special commands for use in the folloing table
819 \newcommand{\XXLLEsl}{\hyperlink{chap:DWLLEstartlengthentry}{start\_length\_entry}
820 \index{DW\_LLE\_start\_length\_entry}}
821 \newcommand{\XXLLEeol}{\hyperlink{chap:DWLLEendoflistentry}{end\_of\_list\_entry}
822 \index{DW\_LLE\_end\_of\_list\_entry}}
826 \begin{tabular}{rl|rr|rl}
827 & entry type & \multicolumn{2}{c}{range}
828 & \multicolumn{2}{l}{\hspace{6mm}location} \\
829 offset & (DW\_LLE\_*) & start & length & length & expression \\
833 0x00 & \XXLLEsl & [9] & 0x002f & 0x0001 & \DWOPregfive~(rdi) \\
834 0x09 & \XXLLEsl & [11] & 0x01b9 & 0x0001 & \DWOPregthree~(rbx) \\
835 0x12 & \XXLLEsl & [29] & 0x0003 & 0x0003 & \DWOPbregtwelve~(r12): -8;\\
836 & & & & & \DWOPstackvalue \\
837 0x1d & \XXLLEsl & [31] & 0x0001 & 0x0003 & \DWOPentryvalue: \\
838 & & & & & (\DWOPregfive~(rdi)); \\
839 & & & & & \DWOPstackvalue \\
840 0x29 & \XXLLEeol &&&& \\
843 0x2a & \XXLLEsl & [9] & 0x002f & 0x0001 & \DWOPregfour~(rsi)) \\
844 0x33 & \XXLLEsl & [11] & 0x01ba & 0x0003 & \DWOPregsix~(rbp)) \\
845 0x3c & \XXLLEsl & [30] & 0x0003 & 0x0003 & \DWOPentryvalue: \\
846 & & & & & (\DWOPregfour~(rsi)); \\
847 & & & & & \DWOPstackvalue \\
848 0x48 & \XXLLEeol &&&& \\
851 0x49 & \XXLLEsl & [10] & 0x0004 & 0x0001 & \DWOPregeighteen~(xmm1) \\
852 0x52 & \XXLLEsl & [11] & 0x01bd & 0x0002 & \DWOPfbreg: -36 \\
853 0x5c & \XXLLEeol &&&& \\
857 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
858 \label{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
861 In each \DWLLEstartlengthentry{}, the start field is the index
862 of a slot in the \dotdebugaddr{} section, relative to the base
863 offset defined by the compilations unit's \DWATaddrbase{}
864 attribute. The \dotdebugaddr{} slots referenced by these entries give
865 the relocated address of a label within the function where the
866 address range begins.
867 The following length field gives the length of the
868 address range. The location, consisting of its own length and
869 a DWARF expression, is last.
872 \section{DWARF Package File Example}
873 \label{app:dwarfpackagefileexample}
874 \addtoindexx{DWARF duplicate elimination!examples}
876 A \addtoindex{DWARF package file}
877 (see Section \refersec{datarep:dwarfpackagefiles})
878 is a collection of split DWARF object files.
879 In general, it will be much smaller than the sum of the split
880 DWARF object files, because the packaging process removes duplicate
881 type units and merges the string tables. Aside from those two
882 optimizations, however, each compilation unit and each type unit
883 from a split DWARF object file is copied verbatim into the package
886 The package file contains the same set of sections as a split
887 DWARF object file, plus two additional sections described below.
889 The packaging utility, like a linker, combines sections of the
890 same name by concatenation. While a split DWARF object may
891 contain multiple \dotdebuginfodwo{} sections, one for the
892 compilation unit, and one for each type unit, a package file
893 contains a single \dotdebuginfodwo{} section. The combined
894 \dotdebuginfodwo{} section contains each compilation unit and one
895 copy of each type unit (discarding any duplicate type
898 As part of merging the string tables, the packaging utility
899 treats the \dotdebugstrdwo{} and \dotdebugstroffsetsdwo{}
900 sections specially. Rather than
901 combining them by simple concatenation, it instead builds a new
902 string table consisting of the unique strings from each input
903 string table. Because all references to these strings use
905 the packaging utility only needs to adjust the
906 string offsets in each \dotdebugstroffsetsdwo{} contribution after
907 building the new \dotdebugstrdwo{} section.
909 Each compilation unit or type unit consists of a set of
910 inter-related contributions to each section in the package file.
911 For example, a compilation unit may have contributions in
912 \dotdebuginfodwo{}, \dotdebugabbrevdwo{}, \dotdebuglinedwo{},
913 \dotdebugstroffsetsdwo{}, and so on. In order to maintain the ability
914 for a consumer to follow references between these sections, the
915 package file contains two additional sections: a compilation unit
916 (CU) index, and a type unit (TU) index. These indexes allow a
917 consumer to look up a compilation unit (by its \CUsignature) or
918 a type unit (by its \TUsignature), and locate each contribution
919 that belongs to that unit.
921 For example, consider a package file, \texttt{demo.dwp}, formed by
922 combining \texttt{demo1.dwo} and \texttt{demo2.dwo} from the previous example
923 (see Appendix \refersec{app:splitdwarfobjectfileexample}). The
924 resulting package file would contain the sections shown in Figure
925 \refersec{fig:sectionsandcontributionsinapackagefile},
926 with contributions from each input file as shown.
930 \begin{tabular}{P{4.7cm}|P{8cm}}
932 \bfseries Section & \bfseries Source of section contributions \\
935 & \dotdebugabbrevdwo{} from \texttt{demo1.dwo} \newline
936 \dotdebugabbrevdwo{} from \texttt{demo2.dwo} \\
938 \dotdebuginfodwo{} \newline (for the compilation units and type units)
939 & compilation unit from \texttt{demo1.dwo} \newline
940 compilation unit from \texttt{demo2.dwo} \newline
941 type unit for class \texttt{Box} from \texttt{demo1.dwo} \newline
942 type unit for class \texttt{Point} from \texttt{demo1.dwo} \newline
943 type unit for class \texttt{Line} from \texttt{demo2.dwo} \\
946 & \dotdebuglocdwo{} from \texttt{demo1.dwo} \newline
947 \dotdebuglocdwo{} from \texttt{demo2.dwo} \\
950 & \dotdebuglinedwo{} from \texttt{demo1.dwo} \newline
951 \dotdebuglinedwo{} from \texttt{demo2.dwo} \\
953 \dotdebugstroffsetsdwo{}
954 & \dotdebugstroffsetsdwo{} from \texttt{demo1.dwo}, \hspace*{6mm}adjusted \newline
955 \dotdebugstroffsetsdwo{} from \texttt{demo2.dwo}, \hspace*{6mm}adjusted \\
958 & merged string table generated by package utility \\
961 & CU index generated by package utility \\
964 & TU index generated by package utility \\
968 \caption{Sections and contributions in example package file \texttt{demo.dwp}}
969 \label{fig:sectionsandcontributionsinapackagefile}
973 The \dotdebugabbrevdwo{}, \dotdebuglocdwo{} and \dotdebuglinedwo{}
974 sections are copied over from the two \texttt{.dwo} files as
975 individual contributions to the corresponding sections in the
977 The offset of each contribution within
978 the combined section and the size of each contribution is recorded
979 as part of the CU and TU index sections.
981 The \dotdebuginfodwo{} sections corresponding to each compilation
982 unit are copied as individual contributions to the combined
983 \dotdebuginfodwo{} section, and one copy of each type unit
984 is also copied. The type units for class \texttt{Box} and class
985 \texttt{Point}, for example, are contained in both \texttt{demo1.dwo}
986 and \texttt{demo2.dwo}, but only one instance of each is copied into
989 The \dotdebugstrdwo{} sections from each file are merged to
990 form a new string table with no duplicates, requiring the
991 adjustment of all references to those strings. The
992 \dotdebugstroffsetsdwo{} sections from the \texttt{.dwo} files
993 are copied as individual contributions, but the string table offset
994 in each slot of those contributions is adjusted to point to
995 the correct offset in the merged string table.
998 The \dotdebugcuindex{} and \dotdebugtuindex{} sections provide a
999 directory to these contributions.
1000 Figure \referfol{fig:examplecuindexsection} shows an example CU
1001 index section containing the two compilation units from
1002 \texttt{demo1.dwo} and \texttt{demo2.dwo}. The CU index shows that
1003 for the compilation unit from \texttt{demo1.dwo}, with \CUsignature{}
1004 \texttt{0x044e413b8a2d1b8f}, its contribution to the \dotdebuginfodwo{}
1005 section begins at offset 0, and is 325 bytes long. For the compilation
1006 unit from \texttt{demo2.dwo}, with \CUsignature{}
1007 \texttt{0xb5f0ecf455e7e97e}, its contribution to the \dotdebuginfodwo{}
1008 section begins at offset 325, and is 673 bytes long.
1010 Likewise, we can find the contributions to the related sections.
1011 In Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts},
1012 we see that the \DWTAGvariable{} DIE at \texttt{7\$} has a
1013 reference to a location list at offset 0x49 (decimal 73). Because
1014 this is part of the compilation unit for \texttt{demo2.dwo}, with
1015 unit signature \texttt{0xb5f0ecf455e7e97e}, we see that its contribution
1016 to \dotdebuglocdwo{} begins at offset 84, so the location list from
1017 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
1018 can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
1019 the combined \dotdebuglocdwo{} section.
1023 \begin{tabular}{lrrrrrr}
1025 \multicolumn{7}{c}{Section header} \\
1027 \multicolumn{2}{l}{Version:}& 5 &&&&\\
1028 \multicolumn{2}{l}{Number of columns:}& 5 &&&&\\
1029 \multicolumn{2}{l}{Number of used entries:}& 2 &&&&\\
1030 \multicolumn{2}{l}{Number of slots:}& 16 &&&&\\
1032 \multicolumn{7}{c}{Offset table} \\
1034 slot& signature& info& abbrev& loc& line& str\_off \\
1035 14& \texttt{0xb5f0ecf455e7e97e}& 325& 452& 84& 52& 72 \\
1036 15& \texttt{0x044e413b8a2d1b8f}& 0& 0& 0& 0& 0 \\
1038 \multicolumn{7}{c}{Size table} \\
1040 slot& & info& abbrev& loc& line& str\_off \\
1041 14& & 673& 593& 93& 52& 120 \\
1042 15& & 325& 452& 84& 52& 72 \\
1046 \caption{Example CU index section}
1047 \label{fig:examplecuindexsection}
1051 Figure \referfol{fig:exampletuindexsection}
1052 shows an example TU index section containing the
1053 three type units for classes \texttt{Box}, \texttt{Point}, and
1054 \texttt{Line}. Each type unit
1055 contains contributions from \dotdebuginfodwo{}, \dotdebugabbrevdwo{},
1056 \dotdebuglinedwo{} and \dotdebugstroffsetsdwo{}. In this example, the
1057 type units for classes \texttt{Box} and \texttt{Point} come from
1058 \texttt{demo1.dwo}, and
1059 share the abbreviations table, line number table, and string
1060 offsets table with the compilation unit from \texttt{demo1.dwo}.
1061 Likewise, the type unit for class \texttt{Line} shares tables
1062 from \texttt{demo2.dwo}.
1064 The sharing of these tables between compilation units and type units
1065 is typical for some implementations, but is not required by the
1070 \begin{tabular}{lrrrrr}
1072 \multicolumn{6}{c}{Section header} \\
1074 \multicolumn{2}{l}{Version:}& 5 \\
1075 \multicolumn{2}{l}{Number of columns:}& 4 \\
1076 \multicolumn{2}{l}{Number of used entries:}& 3 \\
1077 \multicolumn{2}{l}{Number of slots:}& 32 \\
1079 \multicolumn{6}{c}{Offset table} \\
1081 slot& signature& info& abbrev& line& str\_off \\
1082 11& \texttt{0x2f33248f03ff18ab}& 1321& 0& 0& 0 \\
1083 17& \texttt{0x79c7ef0eae7375d1}& 1488& 452& 52& 72 \\
1084 27& \texttt{0xe97a3917c5a6529b}& 998& 0& 0& 0 \\
1086 \multicolumn{6}{c}{Size table} \\
1088 slot& & info& abbrev& line& str\_off \\
1089 11& & 167& 452& 52& 72 \\
1090 17& & 217& 593& 52& 120 \\
1091 27& & 323& 452& 52& 72 \\
1096 \caption{Example TU index section}
1097 \label{fig:exampletuindexsection}