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
45 that need not be accessed by the linker.
48 The optional set of debugging sections includes the following:
51 \dotdebugabbrevdwo{} - Contains the abbreviations table(s) used by
52 the \dotdebuginfodwo{} section.
54 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
55 \DWTAGtypeunit{} DIEs and
56 their descendants. This is the bulk of the debugging
57 information for the compilation unit that is normally found
58 in the \dotdebuginfo{} section.
60 \dotdebugloclistsdwo{} - Contains the location lists referenced by
61 the debugging information entries in the \dotdebuginfodwo{}
62 section. This contains the location lists normally found in
63 the \dotdebugloclists{} section.
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
94 \DWFORMstrxXNor. This allows
95 directory and file name strings to be merged with general
96 strings and across compilations in package files
97 (where they are not subject to potential stripping).
99 In a \texttt{.dwo} file, referring to a string using \DWFORMstrp{}
100 is valid, but such use
101 results in a file that cannot be incorporated into a package file
102 (which involves string merging).
104 In order for the consumer to locate and process the debug
105 information, the compiler must produce a small amount of debug
106 information that passes through the linker into the output
107 binary. A skeleton \dotdebuginfo{} section for each compilation unit
108 contains a reference to the corresponding \texttt{.o} or \texttt{.dwo}
109 file, and the \dotdebugline{} section (which is typically small
110 compared to the \dotdebuginfo{} sections) is
111 linked into the output binary, as is the \dotdebugaddr{} section.
114 The debug sections that continue to be linked into the
115 output binary include the following:
118 \dotdebugabbrev{} - Contains the abbreviation codes used by the
119 skeleton \dotdebuginfo{} section.
121 \dotdebugaddr{} - Contains references to loadable sections,
122 indexed by attributes of
127 or location expression \DWOPaddrx{} opcodes.
129 \dotdebugaranges{} - Contains the accelerated range lookup table
130 for the compilation unit.
132 \dotdebugframe{} - Contains the frame tables.
134 \dotdebuginfo{} - Contains a skeleton
135 skeleton compilation unit DIE, which has no children.
137 \dotdebugline{} - Contains the line number tables.
138 (These could be moved to the .dwo file, but in
139 order to do so, each \DWLNEsetaddress{} opcode would need to
140 be replaced by a new opcode that referenced an entry in the
141 \dotdebugaddr{} section. Furthermore, leaving this section in the
142 .o file allows many debug info consumers to remain unaware of
145 \dotdebuglinestr{} - Contains strings for file names used in
146 combination with the \dotdebugline{} section.
148 \dotdebugnames{} - Contains the names for use in
149 building an index section.
150 The section header refers to a
151 compilation unit offset, which is the offset of the
152 skeleton compilation unit in the \dotdebuginfo{} section.
155 \dotdebugstr{} - Contains any strings referenced by the skeleton
156 \dotdebuginfo{} sections (via \DWFORMstrp{}, \DWFORMstrxXNor{}).
158 \dotdebugstroffsets{} - Contains the string offsets table for
159 the strings in the \dotdebugstr{} section (if
163 \DWFORMstrxXNor{} is used).
167 The skeleton compilation unit DIE may have the following attributes:
169 \begin{nolinenumbersenv}
170 \autocols[0pt]{c}{3}{l}{
179 \DWATstroffsetsbase{}
181 \end{nolinenumbersenv}
183 All other attributes of the compilation unit DIE are moved to
184 the full DIE in the \dotdebuginfodwo{} section.
186 The \HFNdwoid{} field is present in headers of the skeleton DIE
187 and the header of the full DIE, so that a consumer
191 Relocations are neither necessary nor useful in
192 \texttt{.dwo} files, because the \texttt{.dwo}
193 files contain only debugging information that does not need to be
194 processed by a linker. Relocations are rendered unnecessary by
197 \begin{enumerate}[1. ]
198 \item Some values needing relocation are kept in the \texttt{.o} file
199 (for example, references to the line number program from the skeleton
202 \item Some values do not need a relocation because they refer from
203 one \dotdwo{} section to another \dotdwo{} section
204 in the same compilation unit.
206 \item Some values that need a relocation to refer to a relocatable
209 one of the \DWFORMaddrxXNor{} forms,
211 referencing a relocatable
212 value in the \dotdebugaddr{} section (which remains in the .o file).
217 Table \refersec{tab:unitattributesbyunitkind} summarizes which
218 attributes are defined for use in the various
219 kinds of compilation units (see Section \refersec{chap:unitentries}).
220 It compares and contrasts both conventional and split object-related
224 \caption{Unit attributes by unit kind}
225 \label{tab:unitattributesbyunitkind}
226 \begin{tabular}{P{5.5cm}|cc|ccc}
228 & \multicolumn{5}{c}{\bfseries Unit Kind} \\
229 & \multicolumn{2}{c}{\bfseries Conventional}
230 & \multicolumn{3}{c}{\bfseries Skeleton and Split} \\
231 \bfseries Attribute & Full \& & Type & Skeleton & Split Full & Split Type \\
234 \DWATaddrbase & \chkmk & & \chkmk & & \\
236 \DWATbasetypes & \chkmk & & & & \\
238 \DWATcompdir & \chkmk & & \chkmk & & \\
240 %\DWATdwoid & & & \chkmk & \chkmk & \\
242 \DWATdwoname & & & \chkmk & & \\
244 \DWATentrypc & \chkmk & & & \chkmk & \\
246 \DWAThighpc & \chkmk & & \chkmk & & \\
248 \DWATidentifiercase & \chkmk & & & \chkmk & \\
250 \DWATlanguage & \chkmk & \chkmk & & \chkmk & \chkmk \\
252 \DWATloclistsbase & \chkmk & & & &
255 \DWATlowpc & \chkmk & & \chkmk & & \\
257 \DWATmacros & \chkmk & & & \chkmk & \\
259 \DWATmainsubprogram & \chkmk & & & \chkmk & \\
261 \DWATname & \chkmk & & & \chkmk & \\
263 \DWATproducer & \chkmk & & & \chkmk & \\
265 \DWATranges & \chkmk & & & \chkmk & \\
267 \DWATrnglistsbase & \chkmk & & & & \\
269 \DWATstmtlist & \chkmk & \chkmk & \chkmk & & \chkmk \\
271 \DWATstroffsetsbase & \chkmk & \chkmk & \chkmk & & \\
273 \DWATuseUTFeight & \chkmk & \chkmk & \chkmk & \chkmk & \chkmk \\
279 The split dwarf object file design depends on having an index of
280 debugging information available to the consumer. For name lookups,
281 the consumer can use the \dotdebugnames{} index section (see
282 Section \refersec{chap:acceleratedaccess}) to
283 locate a skeleton compilation unit. The
284 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
285 compilation unit can then be used to locate the corresponding
286 DWARF object file for the compilation unit. Similarly, for an
287 address lookup, the consumer can use the \dotdebugaranges{} table,
288 which will also lead to a skeleton compilation unit. For a file
289 and line number lookup, the skeleton compilation units can be
290 used to locate the line number tables.
294 \section{Split DWARF Object File Example}
295 \label{app:splitdwarfobjectfileexample}
296 \addtoindexx{split DWARF object file!example}
297 Consider the example source code in
298 Figure \refersec{fig:splitobjectexamplesourcefragment1},
299 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
300 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
301 When compiled with split DWARF, we will have two DWARF object files,
302 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s},
303 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
305 In this section, we will use this example to show how the
306 connections between the relocatable object file and the split
307 DWARF object file are maintained through the linking process. In
308 the next section, we will use this same example to show how two
309 or more split DWARF object files are combined into a DWARF
314 \textit{File demo1.cc}
318 bool Box::contains(const Point& p) const
320 return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
321 p.y() >= ll_.y() && p.y() <= ur_.y());
324 \caption{Split object example: source fragment \#1}
325 \label{fig:splitobjectexamplesourcefragment1}
329 \textit{File demo2.cc}
333 bool Line::clip(const Box& b)
335 float slope = (end_.y() - start_.y()) / (end_.x() - start_.x());
337 // Trivial acceptance.
338 if (b.contains(start_) && b.contains(end_)) return true;
340 // Trivial rejection.
341 if (start_.x() < b.l() && end_.x() < b.l()) return false;
342 if (start_.x() > b.r() && end_.x() > b.r()) return false;
343 if (start_.y() < b.b() && end_.y() < b.b()) return false;
344 if (start_.y() > b.t() && end_.y() > b.t()) return false;
346 if (b.contains(start_)) {
347 // Swap points so that start_ is outside the clipping
354 if (start_.x() < b.l())
355 start_ = Point(b.l(),
356 start_.y() + (b.l() - start_.x()) * slope);
357 else if (start_.x() > b.r())
358 start_ = Point(b.r(),
359 start_.y() + (b.r() - start_.x()) * slope);
360 else if (start_.y() < b.b())
361 start_ = Point(start_.x() + (b.b() - start_.y()) / slope,
363 else if (start_.y() > b.t())
364 start_ = Point(start_.x() + (b.t() - start_.y()) / slope,
369 \caption{Split object example: source fragment \#2}
370 \label{fig:splitobjectexamplesourcefragment2}
378 Point(float x, float y) : x_(x), y_(y){}
379 float x() const { return x_; }
380 float y() const { return y_; }
388 Line(Point start, Point end) : start_(start), end_(end){}
389 bool clip(const Box& b);
390 Point start() const { return start_; }
391 Point end() const { return end_; }
399 Box(float l, float r, float b, float t) : ll_(l, b), ur_(r, t){}
400 Box(Point ll, Point ur) : ll_(ll), ur_(ur){}
401 bool contains(const Point& p) const;
402 float l() const { return ll_.x(); }
403 float r() const { return ur_.x(); }
404 float b() const { return ll_.y(); }
405 float t() const { return ur_.y(); }
412 \caption{Split object example: source fragment \#3}
413 \label{fig:splitobjectexamplesourcefragment3}
417 \subsection{Contents of the Object Files}
418 The object files each contain the following sections of debug
430 The \dotdebugabbrev{} section contains just a single entry describing
431 the skeleton compilation unit DIE.
433 The DWARF description in the \dotdebuginfo{} section
434 contains just a single DIE, the skeleton compilation unit,
436 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
443 \DWATcompdir: (reference to directory name in .debug_str)
444 \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
445 \DWATaddrbase: (reference to .debug_addr section)
446 \DWATstmtlist: (reference to .debug_line section)
450 \caption{Split object example: skeleton DWARF description}
451 \label{fig:splitdwafexampleskeletondwarfdescription}
454 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
455 location of the corresponding \splitDWARFobjectfile{} that
456 contains the full debug information; that file is normally
457 expected to be in the same directory as the object file itself.
459 The \HFNdwoid{} field in the header of the skeleton unit provides
460 an ID or key for the debug information contained in the
461 DWARF object file. This ID serves
462 two purposes: it can be used to verify that the debug information
463 in the \splitDWARFobjectfile{} matches the information in the object
464 file, and it can be used to find the debug information in a DWARF
467 The \DWATaddrbase{} attribute contains the relocatable offset of
468 this object file's contribution to the \dotdebugaddr{} section.
470 The \DWATstmtlist{} attribute contains the relocatable offset of
471 this file's contribution to the \dotdebugline{} table.
474 The \dotdebugline{} section contains the full line number table for
475 the compiled code in the object file. As shown in
476 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
477 number program header lists the two file names, \texttt{demo.h} and
478 \texttt{demo1.cc}, and contains line number programs for
479 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
481 The \dotdebugstr{} section contains the strings referenced indirectly
482 by the compilation unit DIE and by the line number program.
484 The \dotdebugaddr{} section contains relocatable addresses of
485 locations in the loadable text and data that are referenced by
486 debugging information entries in the split DWARF object. In the
487 example in \refersec{fig:splitobjectexamplesourcefragment3},
488 \texttt{demo1.o} may have three entries:
490 \begin{nolinenumbersenv}
493 Slot & Location referenced \\
495 0 & low PC value for \texttt{Box::contains} \\
496 1 & low PC value for \texttt{Point::x} \\
497 2 & low PC value for \texttt{Point::y} \\
500 \end{nolinenumbersenv}
504 section contains the names defined by the debugging
505 information in the \splitDWARFobjectfile{}
506 (see Section \refersec{chap:contentsofthenameindex}),
507 and references the skeleton compilation unit.
508 When linked together into a final executable,
509 they can be used by a DWARF consumer to lookup a name to find one
510 or more skeleton compilation units that provide information about
511 that name. From the skeleton compilation unit, the consumer can
512 find the \splitDWARFobjectfile{} that it can then read to get the full
515 The \dotdebugaranges{} section contains the PC ranges defined in this
516 compilation unit, and allow a DWARF consumer to map a PC value to
517 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
520 \subsection{Contents of the Linked Executable File}
521 When \texttt{demo1.o} and \texttt{demo2.o} are linked together (along with
522 a main program and other necessary library routines that we will ignore here
523 for simplicity), the resulting executable file will contain at least
524 the two skeleton compilation units in the \dotdebuginfo{} section, as shown in
525 Figure \referfol{fig:splitobjectexampleexecutablefiledwarfexcerpts}.
532 \DWATcompdir: (reference to directory name in \dotdebugstr)
533 \DWATdwoname: (reference to "demo1.dwo" in \dotdebugstr)
534 \DWATaddrbase: 48 (offset in \dotdebugaddr)
535 \DWATstmtlist: 120 (offset in \dotdebugline)
537 \DWATcompdir: (reference to directory name in \dotdebugstr)
538 \DWATdwoname: (reference to "demo2.dwo" in \dotdebugstr)
539 \DWATaddrbase: 80 (offset in \dotdebugaddr)
540 \DWATstmtlist: 200 (offset in \dotdebugline)
544 \caption{Split object example: executable file DWARF excerpts}
545 \label{fig:splitobjectexampleexecutablefiledwarfexcerpts}
548 Each skeleton compilation unit has a \DWATstmtlist{} attribute,
549 which provides the relocated offset to that compilation unit's
550 contribution in the executable's \dotdebugline{} section. In this
551 example, the line number information for \texttt{demo1.dwo} begins at
552 offset 120, and for \texttt{demo2.dwo}, it begins at offset 200.
555 Each skeleton compilation unit also has a \DWATaddrbase{}
556 attribute, which provides the relocated offset to that
557 compilation unit's contribution in the executable's \dotdebugaddr{}
558 section. Unlike the \DWATstmtlist{} attribute, the offset refers
559 to the first address table slot, not to the section header. In
560 this example, we see that the first address (slot 0) from \texttt{demo1.o}
561 begins at offset 48. Because the \dotdebugaddr{} section contains an
562 8-byte header, the object file's contribution to the section
563 actually begins at offset 40 (for a 64-bit DWARF object, the
564 header would be 16 bytes long, and the value for the
565 \DWATaddrbase{} attribute would then be 56). All attributes in
566 \texttt{demo1.dwo} that use
570 would then refer to address
571 table slots relative to that offset. Likewise, the \dotdebugaddr{}
572 contribution from \texttt{demo2.dwo} begins at offset 72, and its first
573 address slot is at offset 80. Because these contributions have
574 been processed by the linker, they contain relocated values for
575 the addresses in the program that are referred to by the debug
578 The linked executable will also contain \dotdebugabbrev,
579 \dotdebugstr{}, \dotdebugnames{} and \dotdebugaranges{} sections, each the
580 result of combining and relocating the contributions from the
581 relocatable object files.
584 \subsection{Contents of the Split DWARF Object Files}
585 The \splitDWARFobjectfile{s} each contain the following sections:
588 \dotdebuginfodwo{} (for the compilation unit)
589 \dotdebuginfodwo{} (one COMDAT section for each type unit)
594 \dotdebugstroffsetsdwo
597 The \dotdebugabbrevdwo{} section contains the abbreviation
598 declarations for the debugging information entries in the
599 \dotdebuginfodwo{} section.
601 The \dotdebuginfodwo{} section containing the compilation unit
602 contains the full debugging information for the compile unit, and
603 looks much like a normal \dotdebuginfo{} section in a non-split
604 object file, with the following exceptions:
606 \item The \DWTAGcompileunit{} DIE does not need to repeat the
607 \DWATranges, \DWATlowpc, \DWAThighpc, and
608 \DWATstmtlist{} attributes that are provided in the skeleton
611 \item References to strings in the string table use the
612 form code \DWFORMstrxXNor, referring to slots in the
613 \dotdebugstroffsetsdwo{} section.
616 \item References to relocatable addresses in the object file use
618 one of the form codes
620 \DWFORMaddrxXNor, referring to slots in the
621 \dotdebugaddr{} table, relative to the base offset given by
622 \DWATaddrbase{} in the skeleton compilation unit.
626 Figure \referfol{fig:splitobjectexampledemoonedwodwarfexcerpts} presents
627 excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
636 \DWATproducer [\DWFORMstrx]: (slot 15) (producer string)
637 \DWATlanguage: \DWLANGCplusplus
638 \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
639 \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
641 \DWATname [\DWFORMstrx]: (slot 12) "Point"
642 \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
643 \DWATdeclaration: true
646 \DWATname [\DWFORMstrx]: (slot 12) "Point"
649 \DWATlinkagename [\DWFORMstrx]: (slot 16) "_ZN5PointC4Eff"
650 \DWATaccessibility: \DWACCESSpublic
651 \DWATdeclaration: true
654 \DWATname [\DWFORMstring]: "Box"
655 \DWATsignature [\DWFORMrefsigeight{}]: 0xe97a3917c5a6529b
656 \DWATdeclaration: true
660 \DWATname [\DWFORMstrx]: (slot 0) "contains"
663 \DWATlinkagename [\DWFORMstrx: (slot 8)
664 "_ZNK3Box8containsERK5Point"
665 \DWATtype: (reference to 7$)
666 \DWATaccessibility: \DWACCESSpublic
667 \DWATdeclaration: true
672 \caption{Split object example: \texttt{demo1.dwo} excerpts}
673 \label{fig:splitobjectexampledemoonedwodwarfexcerpts}
682 \DWATspecification: (reference to 4$)
685 \DWATlowpc [\DWFORMaddrx]: (slot 0)
686 \DWAThighpc [\DWFORMdataeight]: 0xbb
687 \DWATframebase: \DWOPcallframecfa
688 \DWATobjectpointer: (reference to 6$)
689 6$: \DWTAGformalparameter
690 \DWATname [\DWFORMstrx]: (slot 13): "this"
691 \DWATtype: (reference to 8$)
692 \DWATartificial: true
693 \DWATlocation: \DWOPfbreg(-24)
694 \DWTAGformalparameter
695 \DWATname [\DWFORMstring]: "p"
698 \DWATtype: (reference to 11$)
699 \DWATlocation: \DWOPfbreg(-32)
703 \DWATencoding: \DWATEboolean
704 \DWATname [\DWFORMstrx]: (slot 5) "bool"
707 \DWATtype: (reference to 9$)
708 9$: \DWTAGpointertype
710 \DWATtype: (reference to 10$)
712 \DWATtype: (reference to 3$)
715 \DWATtype: (reference to 12$)
716 12$: \DWTAGreferencetype
718 \DWATtype: (reference to 13$)
720 \DWATtype: (reference to 1$)
726 Figure~\ref{fig:splitobjectexampledemoonedwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
731 In the defining declaration for \texttt{Box::contains} at 5\$, the
732 \DWATlowpc{} attribute is represented
734 using \DWFORMaddrx, which refers
736 to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
737 That slot contains the relocated address of the beginning of the
741 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
742 section, and looks like a normal type unit in a non-split object,
743 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
744 attribute that refers to a specialized \dotdebuglinedwo{}
745 \addtoindexx{type unit!specialized \texttt{.debug\_line.dwo} section in}
746 \addtoindexx{specialized \texttt{.debug\_line.dwo} section}
748 section contains a normal line number
749 program header with a list of include directories and filenames,
750 but no line number program. This section is used only as a
751 reference for filenames needed for \DWATdeclfile{} attributes
752 within the type unit.
754 The \dotdebugstroffsetsdwo{} section contains an entry for each
755 unique string in the string table.
756 Each entry in the table is the offset of the string, which is
757 contained in the \dotdebugstrdwo{} section.
759 In a split DWARF object file, all references to
760 strings go through this table (there are no
761 other offsets to \dotdebugstrdwo{} in a split
762 DWARF object file). That is, there
763 is no use of \DWFORMstrp{} in a split DWARF object file.
765 The offsets in these slots have no associated relocations,
766 because they are not part of a relocatable object file.
767 When combined into a DWARF package file, however, each
768 slot must be adjusted to refer to the appropriate offset
769 within the merged string table (\dotdebugstrdwo{}).
770 The tool that builds the DWARF package file must understand
771 the structure of the \dotdebugstroffsetsdwo{} section in
772 order to apply the necessary adjustments.
773 Section \refersec{app:dwarfpackagefileexample} presents
774 an example of a DWARF package file.
777 The \dotdebugrnglistsdwo{} section contains range lists referenced by any
778 \DWATranges{} attributes in the split DWARF object. In our example,
779 \texttt{demo1.o} would have just a single range list for the compilation unit,
780 with range list entries for the function \texttt{Box::contains} and for
781 out-of-line copies of the inline functions \texttt{Point::x} and \texttt{Point::y}.
783 The \dotdebugloclistsdwo{} section contains the location lists referenced
784 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
785 section has a similar format to the \dotdebugloclists{} section in a
786 non-split object, but it has some small differences as explained
787 in Section \refersec{datarep:locationlists}.
795 \DWATname [\DWFORMstrx]: (slot 20) "Line"
796 \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
797 \DWATdeclaration: true
801 \DWATname [\DWFORMstrx]: (slot 19) "clip"
804 \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
805 \DWATtype: (reference to DIE for bool)
806 \DWATaccessibility: \DWACCESSpublic
807 \DWATdeclaration: true
812 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
813 \label{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts}
822 \DWATspecification: (reference to 2$)
825 \DWATlowpc [\DWFORMaddrx]: (slot 32)
826 \DWAThighpc [\DWFORMdataeight]: 0x1ec
827 \DWATframebase: \DWOPcallframecfa
828 \DWATobjectpointer: (reference to 4$)
829 4$: \DWTAGformalparameter
830 \DWATname: (indexed string: 0x11): this
831 \DWATtype: (reference to DIE for type const Point* const)
833 \DWATlocation: 0x0 (location list)
834 5$: \DWTAGformalparameter
838 \DWATtype: (reference to DIE for type const Box& const)
839 \DWATlocation [\DWFORMsecoffset]: 0x2a
840 6$: \DWTAGlexicalblock
841 \DWATlowpc [\DWFORMaddrx]: (slot 17)
844 \DWATname [\DWFORMstrx]: (slot 28): "slope"
847 \DWATtype: (reference to DIE for type float)
848 \DWATlocation [\DWFORMsecoffset]: 0x49
854 Figure~\ref{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
859 In \texttt{demo2.dwo} as shown in
860 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts},
861 the debugging information for \texttt{Line::clip}
862 starting at \texttt{2\$} describes a local
863 variable \texttt{slope} at \texttt{7\$}
864 whose location varies based on the PC.
865 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
866 presents some excerpts from the \dotdebuginfodwo{} section for
871 In Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts},
872 the \DWTAGformalparameter{} entries at \texttt{4\$} and \texttt{5\$} refer to the
873 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
874 \DWTAGvariable{} entry for \texttt{slope}
875 refers to the location list at offset \texttt{0x49}.
876 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
877 shows a representation of the
878 location lists at those offsets in the \dotdebugloclistsdwo{} section.
880 % Special commands for use in the folloing table
881 \newcommand{\XXLLEsl}{\hyperlink{chap:DWLLEstartlength}{start\_length}
882 \index{DW\_LLE\_start\_length}}
883 \newcommand{\XXLLEeol}{\hyperlink{chap:DWLLEendoflist}{end\_of\_list}
884 \index{DW\_LLE\_end\_of\_list}}
889 \begin{tabular}{rl|rr|rl}
890 \multicolumn{2}{c}{\textbf{Entry type}}
891 & \multicolumn{2}{c}{\textbf{Range}}
892 & \multicolumn{2}{l}{\hspace{6mm}\textbf{Counted Location Description}} \\
894 & start& length & length & expression \\
898 0x00 & \XXLLEsl & [9] & 0x002f & \bb 0x01 \eb& \DWOPregfive~(rdi) \\
899 0x09 & \XXLLEsl & [11] & 0x01b9 & \bb 0x01 \eb& \DWOPregthree~(rbx) \\
900 0x12 & \XXLLEsl & [29] & 0x0003 & \bb 0x03 \eb& \DWOPbregtwelve~(r12): -8;\\
901 & & & & & \DWOPstackvalue \\
902 0x1d & \XXLLEsl & [31] & 0x0001 & \bb 0x03 \eb& \DWOPentryvalue: \\
903 & & & & & (\DWOPregfive~(rdi)); \\
904 & & & & & \DWOPstackvalue \\
905 0x29 & \XXLLEeol &&&& \\
908 0x2a & \XXLLEsl & [9] & 0x002f & \bb 0x01 \eb& \DWOPregfour~(rsi)) \\
909 0x33 & \XXLLEsl & [11] & 0x01ba & \bb 0x03 \eb& \DWOPregsix~(rbp)) \\
910 0x3c & \XXLLEsl & [30] & 0x0003 & \bb 0x03 \eb& \DWOPentryvalue: \\
911 & & & & & (\DWOPregfour~(rsi)); \\
912 & & & & & \DWOPstackvalue \\
913 0x48 & \XXLLEeol &&&& \\
916 0x49 & \XXLLEsl & [10] & 0x0004 & \bb 0x01 \eb& \DWOPregeighteen~(xmm1) \\
917 0x52 & \XXLLEsl & [11] & 0x01bd & \bb 0x02 \eb& \DWOPfbreg: -36 \\
918 0x5c & \XXLLEeol &&&& \\
923 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebugloclistsdwo{} excerpts}
924 \label{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
927 In each \DWLLEstartlength{} entry,
928 the start field is the index
929 of a slot in the \dotdebugaddr{} section, relative to the base
930 offset defined by the compilations unit's \DWATaddrbase{}
931 attribute. The \dotdebugaddr{} slots referenced by these entries give
932 the relocated address of a label within the function where the
933 address range begins.
934 The following length field gives the length of the
935 address range. The location, consisting of its own length and
936 a DWARF expression, is last.
939 \section{DWARF Package File Example}
940 \label{app:dwarfpackagefileexample}
941 \addtoindexx{DWARF duplicate elimination!examples}
943 A \addtoindex{DWARF package file}
944 (see Section \refersec{datarep:dwarfpackagefiles})
945 is a collection of split DWARF object files.
946 In general, it will be much smaller than the sum of the split
947 DWARF object files, because the packaging process removes duplicate
948 type units and merges the string tables. Aside from those two
949 optimizations, however, each compilation unit and each type unit
950 from a split DWARF object file is copied verbatim into the package
953 The package file contains the same set of sections as a split
954 DWARF object file, plus two additional sections described below.
956 The packaging utility, like a linker, combines sections of the
957 same name by concatenation. While a split DWARF object may
958 contain multiple \dotdebuginfodwo{} sections, one for the
959 compilation unit, and one for each type unit, a package file
960 contains a single \dotdebuginfodwo{} section. The combined
961 \dotdebuginfodwo{} section contains each compilation unit and one
962 copy of each type unit (discarding any duplicate type
965 As part of merging the string tables, the packaging utility
966 treats the \dotdebugstrdwo{} and \dotdebugstroffsetsdwo{}
967 sections specially. Rather than
968 combining them by simple concatenation, it instead builds a new
969 string table consisting of the unique strings from each input
970 string table. Because all references to these strings use
972 the packaging utility only needs to adjust the
973 string offsets in each \dotdebugstroffsetsdwo{} contribution after
974 building the new \dotdebugstrdwo{} section.
976 Each compilation unit or type unit consists of a set of
977 inter-related contributions to each section in the package file.
978 For example, a compilation unit may have contributions in
979 \dotdebuginfodwo{}, \dotdebugabbrevdwo{}, \dotdebuglinedwo{},
980 \dotdebugstroffsetsdwo{}, and so on. In order to maintain the ability
981 for a consumer to follow references between these sections, the
982 package file contains two additional sections: a compilation unit
983 (CU) index, and a type unit (TU) index. These indexes allow a
984 consumer to look up a compilation unit (by its \CUsignature) or
985 a type unit (by its \TUsignature), and locate each contribution
986 that belongs to that unit.
988 For example, consider a package file, \texttt{demo.dwp}, formed by
989 combining \texttt{demo1.dwo} and \texttt{demo2.dwo} from the previous example
990 (see Appendix \refersec{app:splitdwarfobjectfileexample}).
991 For an executable file named "\texttt{demo}" (or "\texttt{demo.exe}"), a debugger would
992 typically expect to find \texttt{demo.dwp} in the same directory as the
994 The resulting package file would contain the sections shown in Figure
995 \refersec{fig:sectionsandcontributionsinapackagefile},
996 with contributions from each input file as shown.
1000 \begin{tabular}{P{4.7cm}|P{8cm}}
1002 \bfseries Section & \bfseries Source of section contributions \\
1004 \dotdebugabbrevdwo{}
1005 & \dotdebugabbrevdwo{} from \texttt{demo1.dwo} \newline
1006 \dotdebugabbrevdwo{} from \texttt{demo2.dwo} \\
1008 \dotdebuginfodwo{} \newline (for the compilation units and type units)
1009 & compilation unit from \texttt{demo1.dwo} \newline
1010 compilation unit from \texttt{demo2.dwo} \newline
1011 type unit for class \texttt{Box} from \texttt{demo1.dwo} \newline
1012 type unit for class \texttt{Point} from \texttt{demo1.dwo} \newline
1013 type unit for class \texttt{Line} from \texttt{demo2.dwo} \\
1015 \dotdebugrnglistsdwo{}
1016 & \dotdebugrnglistsdwo{} from \texttt{demo1.dwo} \newline
1017 \dotdebugrnglistsdwo{} from \texttt{demo2.dwo} \\
1019 \dotdebugloclistsdwo{}
1020 & \dotdebugloclistsdwo{} from \texttt{demo1.dwo} \newline
1021 \dotdebugloclistsdwo{} from \texttt{demo2.dwo} \\
1024 & \dotdebuglinedwo{} from \texttt{demo1.dwo} \newline
1025 \dotdebuglinedwo{} from \texttt{demo2.dwo} \\
1027 \dotdebugstroffsetsdwo{}
1028 & \dotdebugstroffsetsdwo{} from \texttt{demo1.dwo}, \hspace*{6mm}adjusted \newline
1029 \dotdebugstroffsetsdwo{} from \texttt{demo2.dwo}, \hspace*{6mm}adjusted \\
1032 & merged string table generated by package utility \\
1035 & CU index generated by package utility \\
1038 & TU index generated by package utility \\
1042 \caption{Sections and contributions in example package file \texttt{demo.dwp}}
1043 \label{fig:sectionsandcontributionsinapackagefile}
1047 The \dotdebugabbrevdwo{}, \dotdebugrnglistsdwo{},
1048 \dotdebugloclistsdwo{} and \dotdebuglinedwo{}
1049 sections are copied over from the two \texttt{.dwo} files as
1050 individual contributions to the corresponding sections in the
1052 The offset of each contribution within
1053 the combined section and the size of each contribution is recorded
1054 as part of the CU and TU index sections.
1056 The \dotdebuginfodwo{} sections corresponding to each compilation
1057 unit are copied as individual contributions to the combined
1058 \dotdebuginfodwo{} section, and one copy of each type unit
1059 is also copied. The type units for class \texttt{Box} and class
1060 \texttt{Point}, for example, are contained in both \texttt{demo1.dwo}
1061 and \texttt{demo2.dwo}, but only one instance of each is copied into
1065 The \dotdebugstrdwo{} sections from each file are merged to
1066 form a new string table with no duplicates, requiring the
1067 adjustment of all references to those strings. The
1068 \dotdebugstroffsetsdwo{} sections from the \texttt{.dwo} files
1069 are copied as individual contributions, but the string table offset
1070 in each slot of those contributions is adjusted to point to
1071 the correct offset in the merged string table.
1073 The \dotdebugcuindex{} and \dotdebugtuindex{} sections provide a
1074 directory to these contributions.
1075 Figure \referfol{fig:examplecuindexsection} shows an example CU
1076 index section containing the two compilation units from
1077 \texttt{demo1.dwo} and \texttt{demo2.dwo}. The CU index shows that
1078 for the compilation unit from \texttt{demo1.dwo}, with \CUsignature{}
1079 \texttt{0x044e413b8a2d1b8f}, its contribution to the \dotdebuginfodwo{}
1080 section begins at offset 0, and is 325 bytes long. For the compilation
1081 unit from \texttt{demo2.dwo}, with \CUsignature{}
1082 \texttt{0xb5f0ecf455e7e97e}, its contribution to the \dotdebuginfodwo{}
1083 section begins at offset 325, and is 673 bytes long.
1085 Likewise, we can find the contributions to the related sections.
1086 In Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts},
1087 we see that the \DWTAGvariable{} DIE at \texttt{7\$} has a
1088 reference to a location list at offset 0x49 (decimal 73). Because
1089 this is part of the compilation unit for \texttt{demo2.dwo}, with
1090 unit signature \texttt{0xb5f0ecf455e7e97e}, we see that its contribution
1091 to \dotdebugloclistsdwo{} begins at offset 84, so the location list from
1092 Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
1093 can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
1094 the combined \dotdebugloclistsdwo{} section.
1098 \begin{tabular}{lrrrrrrr}
1100 \multicolumn{7}{c}{Section header} \\
1102 \multicolumn{2}{l}{Version:}& 5 &&&&&\\
1103 \multicolumn{2}{l}{Number of columns:}& 6 &&&&&\\
1104 \multicolumn{2}{l}{Number of used entries:}& 2 &&&&&\\
1105 \multicolumn{2}{l}{Number of slots:}& 16 &&&&&\\
1107 \multicolumn{7}{c}{Offset table} \\
1109 slot& signature& info& abbrev& loc& line& str\_off& rng \\ \\
1110 14& \texttt{0xb5f0ecf455e7e97e} & 325& 452& 84& 52& 72& 350 \\
1111 15& \texttt{0x044e413b8a2d1b8f} & 0& 0& 0& 0& 0& 0 \\
1113 \multicolumn{7}{c}{Size table} \\
1115 slot& & info& abbrev& loc& line& str\_off& rng \\ \\
1116 14& & 673& 593& 93& 52& 120& 34 \\
1117 15& & 325& 452& 84& 52& 72& 15 \\
1121 \caption{Example CU index section}
1122 \label{fig:examplecuindexsection}
1126 Figure \referfol{fig:exampletuindexsection}
1127 shows an example TU index section containing the
1128 three type units for classes \texttt{Box}, \texttt{Point}, and
1129 \texttt{Line}. Each type unit
1130 contains contributions from \dotdebuginfodwo{}, \dotdebugabbrevdwo{},
1131 \dotdebuglinedwo{} and \dotdebugstroffsetsdwo{}. In this example, the
1132 type units for classes \texttt{Box} and \texttt{Point} come from
1133 \texttt{demo1.dwo}, and
1134 share the abbreviations table, line number table, and string
1135 offsets table with the compilation unit from \texttt{demo1.dwo}.
1136 Likewise, the type unit for class \texttt{Line} shares tables
1137 from \texttt{demo2.dwo}.
1139 The sharing of these tables between compilation units and type units
1140 is typical for some implementations, but is not required by the
1145 \begin{tabular}{lrrrrr}
1147 \multicolumn{6}{c}{Section header} \\
1149 \multicolumn{2}{l}{Version:}& 5 \\
1150 \multicolumn{2}{l}{Number of columns:}& 4 \\
1151 \multicolumn{2}{l}{Number of used entries:}& 3 \\
1152 \multicolumn{2}{l}{Number of slots:}& 32 \\
1154 \multicolumn{6}{c}{Offset table} \\
1156 slot& signature& info& abbrev& line& str\_off \\ \\
1157 11& \texttt{0x2f33248f03ff18ab}& 1321& 0& 0& 0 \\
1158 17& \texttt{0x79c7ef0eae7375d1}& 1488& 452& 52& 72 \\
1159 27& \texttt{0xe97a3917c5a6529b}& 998& 0& 0& 0 \\
1161 \multicolumn{6}{c}{Size table} \\
1163 slot& & info& abbrev& line& str\_off \\ \\
1164 11& & 167& 452& 52& 72 \\
1165 17& & 217& 593& 52& 120 \\
1166 27& & 323& 452& 52& 72 \\
1171 \caption{Example TU index section}
1172 \label{fig:exampletuindexsection}