Merge branch 'HEAD' of dwarfgit@dwarfstd.org:dwarf-doc.git
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
1 \chapter[Split DWARF Object Files (Informative)]{Split DWARF Object Files (Informative)}
2 \label{app:splitdwarfobjectsinformative}
3 \addtoindexx{DWARF compression}
4 \addtoindexx{DWARF duplicate elimination|see{\textit{also} DWARF compression}}
5 \addtoindexx{DWARF duplicate elimination|see{\textit{also} split DWARF object file}}
6 With the traditional DWARF format, debug information is designed
7 with the expectation that it will be processed by the linker to
8 produce an output binary with complete debug information, and
9 with fully-resolved references to locations within the
10 application. For very large applications, however, this approach
11 can result in excessively large link times and excessively large
12 output files. 
13
14 Several vendors have independently developed
15 proprietary approaches that allow the debug information to remain
16 in the relocatable object files, so that the linker does not have
17 to process the debug information or copy it to the output file.
18 These approaches have all required that additional information be
19 made available to the debug information consumer, and that the
20 consumer perform some minimal amount of relocation in order to
21 interpret the debug info correctly. The additional information
22 required, in the form of load maps or symbol tables, and the
23 details of the relocation are not covered by the DWARF
24 specification, and vary with each vendor's implementation.
25
26 Section \refersec{datarep:splitdwarfobjectfiles} describes a
27 platform-independent mechanism that allows a producer to
28 split the debugging information into relocatable and
29 non-relocatable partitions. This Appendix describes the use
30 of \splitDWARFobjectfile{s} and provides some illustrative
31 examples.
32
33 \section{Overview}
34 \label{app:splitoverview}
35 \DWARFVersionV{} introduces an optional set of debugging sections
36 that allow the compiler to partition the debugging information
37 into a set of (small) sections that require link-time relocation
38 and a set of (large) sections that do not. The sections that
39 require relocation are written to the relocatable object file as
40 usual, and are linked into the final executable. The sections
41 that do not require relocation, however, can be written to the
42 relocatable object (.o) file but ignored by the linker, or they
43 can be written to a separate DWARF object (.dwo{}) 
44 \addtoindexx{\texttt{.dwo} file extension} file.
45
46 \needlines{4}
47 The optional set of debugging sections includes the following:
48 \begin{itemize}
49 \item
50 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
51 \DWTAGtypeunit{} DIEs and
52 their descendants. This is the bulk of the debugging
53 information for the compilation unit that is normally found
54 in the \dotdebuginfo{} section.
55 \item
56 \dotdebugabbrevdwo{} - Contains the abbreviations table(s) used by
57 the \dotdebuginfodwo{} section.
58 \item
59 \dotdebuglocdwo{} - Contains the location lists referenced by
60 the debugging information entries in the \dotdebuginfodwo{}
61 section. This contains the location lists normally found in 
62 the \dotdebugloc{} section,
63 with a slightly modified format to eliminate the need for
64 relocations.
65 \item
66 \dotdebugstrdwo{} - Contains the string table for all indirect
67 strings referenced by the debugging information in the
68 \dotdebuginfodwo{} sections.
69 \item
70 \dotdebugstroffsetsdwo{} - Contains the string offsets table
71 for the strings in the \dotdebugstrdwo{}{} section.
72 \item
73 \dotdebugmacrodwo{} - Contains macro definition information,
74 normally found in the \dotdebugmacro{} section.
75 \item
76 \dotdebuglinedwo{} - Contains \addtoindex{specialized line number table}s 
77 for the type units in the \dotdebuginfodwo{} section. These tables
78 contain only the directory and filename lists needed to
79 interpret \DWATdeclfile{} attributes in the debugging
80 information entries. Actual line number tables remain in the
81 \dotdebugline{} section, and remain in the relocatable object
82 (.o) files.
83
84 \end{itemize}
85
86 In a \texttt{.dwo} file there is no benefit to having a separate string
87 section for directories and file names because the primary
88 string table will never be stripped. Accordingly, no
89 \texttt{.debug\_line\_str.dwo} section is defined. Content descriptions 
90 corresponding to \DWFORMlinestrp{} in an executable file (for example, 
91 in the skeleton compilation unit) instead use \DWFORMstrx. This allows
92 directory and file name strings to be merged with general
93 strings and across compilations in package files (which are not
94 subject to potential stripping).
95
96 In a \texttt{.dwo} file. referring to a string using \DWFORMstrp{}
97 is valid, but such use may complicate incorporation of that file into a
98 \texttt{.dwp} file due to changed string offsets as a result of string merging.
99
100 In order for the consumer to locate and process the debug
101 information, the compiler must produce a small amount of debug
102 information that passes through the linker into the output
103 binary. A skeleton \dotdebuginfo{} section for each compilation unit
104 contains a reference to the corresponding \texttt{.o} or \texttt{.dwo}
105 file, and the \dotdebugline{} section (which is typically small
106 compared to the \dotdebuginfo{} sections) is
107 linked into the output binary, as is the new \dotdebugaddr{}
108 section.
109
110 \needlines{6}
111 The debug sections that continue to be linked into the
112 output binary include the following:
113 \begin{itemize}
114 \item
115 \dotdebugabbrev{} - Contains the abbreviation codes used by the
116 skeleton \dotdebuginfo{} section.
117 \item
118 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
119 but no children.
120 \item
121 \dotdebugstr{} - Contains any strings referenced by the skeleton
122 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
123 \item
124 \dotdebugstroffsets{} - Contains the string offsets table for
125 the strings in the \dotdebugstr{} section.
126 \item
127 \dotdebugaddr{} - Contains references to loadable sections,
128 indexed by attributes of form \DWFORMaddrx{} or location
129 expression \DWOPaddrx{} opcodes.
130 \item
131 \dotdebugline{} - Contains the line number tables, unaffected by
132 this design. (These could be moved to the .dwo file, but in
133 order to do so, each \DWLNEsetaddress{} opcode would need to
134 be replaced by a new opcode that referenced an entry in the
135 \dotdebugaddr{} section. Furthermore, leaving this section in the
136 .o file allows many debug info consumers to remain unaware of
137 .dwo files.)
138 \item
139 \dotdebugframe{} - Contains the frame tables, unaffected by this
140 design.
141 \item
142 \dotdebugranges{} - Contains the range lists, unaffected by this
143 design.
144 \item
145 \dotdebugnames{} - Contains the names for use in
146 building an index section. This section has the same
147 format and use as always. The section header refers to a
148 compilation unit offset, which is the offset of the
149 skeleton compilation unit in the \dotdebuginfo{} section.
150 \item
151 \dotdebugaranges{} - Contains the accelerated range lookup table
152 for the compilation unit, unaffected by this design.
153 \end{itemize}
154
155 \needlines{6}
156 The skeleton \DWTAGcompileunit{} DIE has the following attributes:
157 \autocols[0pt]{c}{3}{l}{
158 \DWATaddrbase{},
159 \DWATcompdir{},
160 \DWATdwoname{},
161 \DWATdwoid{},
162 \DWAThighpc{} \dag,
163 \DWATlowpc{} \dag,
164 \DWATranges{} \dag,
165 \DWATrangesbase{},
166 \DWATstmtlist{},
167 \DWATstroffsetsbase{}
168 }
169 \dag{} If \DWATranges{} is present, the \DWATlowpc{}/\DWAThighpc{}
170 pair is not used, although \DWATlowpc{} may still be present
171 to provide a default base address for range list entries.
172 Conversely, if the \DWATlowpc/\linebreak[0]\DWAThighpc{} pair is
173 present, then \DWATranges{} is not used.
174
175 All other attributes of the compilation unit DIE are moved to
176 the full DIE in the \dotdebuginfodwo{} section.
177 The \DWATdwoid{} attribute is present
178 in both the skeleton DIE and the full DIE, so that a consumer
179 can verify a match.
180
181 \needlines{4}
182 Because of other improvements in \DWARFVersionV, most of the
183 relocations that would normally be found in the \dotdebuginfodwo{}
184 sections are moved to the \dotdebugaddr{} and
185 \dotdebugstroffsetsdwo{} sections. Those in the
186 \dotdebugstroffsetsdwo{} sections are simply omitted because the
187 DWARF information in those sections is not combined at link
188 time, so no relocation is necessary. Similarly,
189 many of the remaining relocations referring to range lists are
190 eliminated. 
191
192 The relocations that remain fall into the following categories:
193 \begin{itemize}
194 \item
195 References from compilation unit and type unit headers to the
196 \dotdebugabbrevdwo{} section. Because the new sections are not
197 combined at link time, these references need no relocations.
198 \item
199 References from \DWTAGcompileunit{} DIEs to the
200 \dotdebuglinedwo{} section, via \DWATstmtlist{}. This attribute
201 remains in the skeleton \dotdebuginfo{} section, so no
202 relocation in the \dotdebuginfodwo{} section is necessary.
203 \item
204 References from \DWTAGtypeunit{} DIEs to the 
205 \dotdebuglinedwo{} section, via \DWATstmtlist{}. Because the new
206 sections are not combined at link time, these references need
207 no relocations.
208 \item
209 References from \DWTAGcompileunit{} and \DWTAGtypeunit{} DIEs
210 to the \dotdebugstroffsetsdwo{} section, via
211 \DWATstroffsetsbase{}. Because the new sections are not
212 combined at link time, the \DWATstroffsetsbase{} attribute
213 is not required in a \dotdebuginfodwo{}
214 section.
215 \item
216 References from \DWTAGcompileunit{} DIEs to the \dotdebugaddr{}
217 section, via \DWATaddrbase{}. This attribute remains in
218 the skeleton \dotdebuginfo{} section, so no relocation in the
219 \dotdebuginfodwo{} section is necessary.
220 \needlines{4}
221 \item
222 References from \DWTAGcompileunit{} DIEs to the \dotdebugranges{}
223 section, via \DWATrangesbase{}. This attribute remains in
224 the skeleton \dotdebuginfo{} section, so no relocation in the
225 \dotdebuginfodwo{} section is necessary.
226 \item
227 References from the \dotdebuglocdwo{} section to machine addresses
228 via a location list entry or a base address selection entry.
229 With a minor change to the location list entry format,
230 described below, these relocations are also eliminated.
231
232 \needlines{4}
233 Each location list entry contains beginning and ending address
234 offsets, which normally may be relocated addresses. In the
235 \dotdebuglocdwo{} section, these offsets are replaced by indices
236 into the \dotdebugaddr{} section (see Section 
237 \refersec{chap:locationlistsinsplitobjectfiles} for details). 
238 \end{itemize}
239
240 \needlines{8}
241 The split dwarf object file design depends on having an index of 
242 debugging information available to the consumer. For name lookups, 
243 the consumer can use the \dotdebugnames{} index section (see 
244 Section \refersec{chap:acceleratedaccess}) to 
245 locate a skeleton compilation unit. The
246 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
247 compilation unit can then be used to locate the corresponding
248 DWARF object file for the compilation unit. Similarly, for an
249 address lookup, the consumer can use the \dotdebugaranges{} table,
250 which will also lead to a skeleton compilation unit. For a file
251 and line number lookup, the skeleton compilation units can be
252 used to locate the line number tables.
253
254 \clearpage
255
256 \section{Split DWARF Object File Example}
257 \label{app:splitdwarfobjectfileexample}
258 \addtoindexx{split DWARF object file!example}
259 Consider the example source code in 
260 Figure \refersec{fig:splitobjectexamplesourcefragment1}, 
261 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
262 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
263 When compiled with split DWARF, we will have two object files,
264 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s}, 
265 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
266
267 \begin{figure}[b]
268 \textit{File demo1.cc}
269 \begin{lstlisting}
270 #include "demo.h"
271
272 bool Box::contains(const Point& p) const
273 {
274     return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
275             p.y() >= ll_.y() && p.y() <= ur_.y());
276 }
277 \end{lstlisting}
278 \caption{Split object example: source fragment \#1}
279 \label{fig:splitobjectexamplesourcefragment1}
280 \end{figure}
281
282 \begin{figure}[h]
283 \textit{File demo2.cc}
284 \begin{lstlisting}
285 #include "demo.h"
286
287 bool Line::clip(const Box& b)
288 {
289   float slope = (end_.y() - start_.y()) / (end_.x() - start_.x());
290   while (1) {
291     // Trivial acceptance.
292     if (b.contains(start_) && b.contains(end_)) return true;
293
294     // Trivial rejection.
295     if (start_.x() < b.l() && end_.x() < b.l()) return false;
296     if (start_.x() > b.r() && end_.x() > b.r()) return false;
297     if (start_.y() < b.b() && end_.y() < b.b()) return false;
298     if (start_.y() > b.t() && end_.y() > b.t()) return false;
299
300     if (b.contains(start_)) {
301       // Swap points so that start_ is outside the clipping 
302       // rectangle.
303       Point temp = start_;
304       start_ = end_;
305       end_ = temp;
306     }
307
308     if (start_.x() < b.l())
309       start_ = Point(b.l(), 
310                      start_.y() + (b.l() - start_.x()) * slope);
311     else if (start_.x() > b.r())
312       start_ = Point(b.r(), 
313                      start_.y() + (b.r() - start_.x()) * slope);
314     else if (start_.y() < b.b())
315       start_ = Point(start_.x() + (b.b() - start_.y()) / slope, 
316                      b.b());
317     else if (start_.y() > b.t())
318       start_ = Point(start_.x() + (b.t() - start_.y()) / slope, 
319                      b.t());
320   }
321 }
322 \end{lstlisting}
323 \caption{Split object example: source fragment \#2}
324 \label{fig:splitobjectexamplesourcefragment2}
325 \end{figure}
326
327 \begin{figure}[h]
328 \textit{File demo.h}
329 \begin{lstlisting}
330 class A {
331   public:
332     Point(float x, float y) : x_(x), y_(y){}
333     float x() const { return x_; }
334     float y() const { return y_; }
335   private:
336     float x_;
337     float y_;
338 };
339
340 class Line {
341   public:
342     Line(Point start, Point end) : start_(start), end_(end){}
343     bool clip(const Box& b);
344     Point start() const { return start_; }
345     Point end() const { return end_; }
346   private:
347     Point start_;
348     Point end_;
349 };
350
351 class Box {
352   public:
353     Box(float l, float r, float b, float t) : ll_(l, b), ur_(r, t){}
354     Box(Point ll, Point ur) : ll_(ll), ur_(ur){}
355     bool contains(const Point& p) const;
356     float l() const { return ll_.x(); }
357     float r() const { return ur_.x(); }
358     float b() const { return ll_.y(); }
359     float t() const { return ur_.y(); }
360   private:
361     Point ll_;
362     Point ur_;
363 };
364
365 \end{lstlisting}
366 \caption{Split object example: source fragment \#3}
367 \label{fig:splitobjectexamplesourcefragment3}
368 \end{figure}
369
370 \clearpage
371 \subsection{Contents of the Object File}
372 The object files each contain the following sections of debug
373 information:
374 \begin{alltt}
375   \dotdebugabbrev
376   \dotdebuginfo
377   \dotdebugranges
378   \dotdebugline
379   \dotdebugstr
380   \dotdebugaddr
381   \dotdebugnames
382   \dotdebugaranges
383 \end{alltt}
384
385 The \dotdebugabbrev{} section contains just a single entry describing
386 the skeleton compilation unit DIE.
387
388 The DWARF description in the \dotdebuginfo{} section 
389 contains just a single DIE, the skeleton compilation unit, 
390 which may look like 
391 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
392
393 \begin{figure}[h]
394 \begin{dwflisting}
395 \begin{alltt}
396
397     \DWTAGcompileunit
398       \DWATcompdir: (reference to directory name in .debug_str)
399       \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
400       \DWATdwoid: 0x44e413b8a2d1b8f
401       \DWATaddrbase: (reference to .debug_addr section)
402       \DWATrangesbase: (reference to range list in .debug_ranges section)
403       \DWATranges: (offset of range list in .debug_ranges section)
404       \DWATstmtlist: (reference to .debug_line section)
405       \DWATlowpc: 0
406       
407 \end{alltt}
408 \end{dwflisting}
409 \caption{Split object example: Skeleton DWARF description}
410 \label{fig:splitdwafexampleskeletondwarfdescription}
411 \end{figure}
412
413 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
414 location of the corresponding \splitDWARFobjectfile{} that
415 contains the full debug information; that file is normally
416 expected to be in the same directory as the object file itself.
417
418 The \DWATdwoid{} attribute provides a hash of the debug
419 information contained in the \splitDWARFobjectfile. This hash serves
420 two purposes: it can be used to verify that the debug information
421 in the \splitDWARFobjectfile{} matches the information in the object
422 file, and it can be used to find the debug information in a DWARF
423 package file.
424
425 \needlines{4}
426 The \DWATaddrbase{} attribute contains the relocatable offset of
427 this object file's contribution to the \dotdebugaddr{} section, and
428 the \DWATrangesbase{} attribute contains the relocatable offset
429 of this object file's contribution to the \dotdebugranges{} section.
430 The \DWATranges{} attribute refers to a specific range list within
431 that contribution, and its value is a (non-relocatable) offset
432 relative to the base. In a compilation unit with a single
433 contiguous range of code, the \DWATranges{} attribute might be
434 omitted, and instead replaced by the pair \DWATlowpc{} and
435 \DWAThighpc.
436
437 The \DWATstmtlist{} attribute contains the relocatable offset of
438 this file's contribution to the \dotdebugline{} table.
439
440 If there is a \DWATranges{} attribute, the \DWATlowpc{} attribute
441 provides a default base address for the range list entries in the
442 \dotdebugranges{} section. It may be omitted if each range list entry
443 provides an explicit base address selection entry; it may provide
444 a relocatable base address, in which case the offsets in each
445 range list entry are relative to it; or it may have the value 0,
446 in which case the offsets in each range list entry are themselves
447 relocatable addresses.
448
449 The \dotdebugranges{} section contains the range list referenced by
450 the \DWATranges{} attribute in the skeleton compilation unit DIE,
451 plus any range lists referenced by \DWATranges{} attributes in the
452 split DWARF object. In our example, \texttt{demo1.o} would contain range
453 list entries for the function \texttt{Box::contains}, as well as for
454 out-of-line copies of the inline functions \texttt{Point::x} and 
455 \texttt{Point::y}.
456
457 The \dotdebugline{} section contains the full line number table for
458 the compiled code in the object file. In the example in
459 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
460 number program header would list the two files, \texttt{demo.h} and
461 \texttt{demo1.cc}, and would contain line number programs for
462 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
463
464 The \dotdebugstr{} section contains the strings referenced indirectly
465 by the compilation unit DIE and by the line number program.
466
467 The \dotdebugaddr{} section contains relocatable addresses of
468 locations in the loadable text and data that are referenced by
469 debugging information entries in the split DWARF object. In the
470 example in \refersec{fig:splitobjectexamplesourcefragment3}, 
471 \texttt{demo1.o} may have three entries:
472 \begin{center}
473 %\footnotesize
474 \begin{tabular}{cl}
475 Slot & Location referenced \\
476 \hline
477    0   &  low PC value for \texttt{Box::contains}  \\
478    1   &  low PC value for \texttt{Point::x}       \\
479    2   &  low PC value for \texttt{Point::y}       \\
480 \end{tabular}
481 \end{center}
482
483 \needlines{4}
484 The \dotdebugnames{}
485 section contains the names defined by the debugging
486 information in the \splitDWARFobjectfile{} 
487 (see Section \refersec{chap:contentsofthenameindex}, 
488 and references the skeleton compilation unit. 
489 When linked together into a final executable,
490 they can be used by a DWARF consumer to lookup a name to find one
491 or more skeleton compilation units that provide information about
492 that name. From the skeleton compilation unit, the consumer can
493 find the \splitDWARFobjectfile{} that it can then read to get the full
494 DWARF information.
495
496 The \dotdebugaranges{} section contains the PC ranges defined in this
497 compilation unit, and allow a DWARF consumer to map a PC value to
498 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
499
500
501 \subsection{Contents of the Split DWARF Object Files}
502 The \splitDWARFobjectfile{s} each contain the following sections:
503 \begin{alltt}
504   \dotdebugabbrevdwo
505   \dotdebuginfodwo{} (for the compilation unit)
506   \dotdebuginfodwo{} (one COMDAT section for each type unit)
507   \dotdebuglocdwo
508   \dotdebuglinedwo
509   \dotdebugmacrodwo
510   \dotdebugstroffsetsdwo
511   \dotdebugstrdwo
512 \end{alltt}
513 The \dotdebugabbrevdwo{} section contains the abbreviation
514 declarations for the debugging information entries in the
515 \dotdebuginfodwo{} section. In general, it looks just like a normal
516 \dotdebugabbrev{} section in a non-split object file.
517
518 The \dotdebuginfodwo{} section containing the compilation unit
519 contains the full debugging information for the compile unit, and
520 looks much like a normal \dotdebuginfo{} section in a non-split
521 object file, with the following exceptions:
522 \begin{itemize}
523 \item The \DWTAGcompileunit{} DIE does not need to repeat the
524 \DWATranges, \DWATlowpc, \DWAThighpc, and
525 \DWATstmtlist{} attributes that are provided in the skeleton
526 compilation unit.
527
528 \item References to strings in the string table use the new form
529 code \DWFORMstrx, referring to slots in the
530 \dotdebugstroffsetsdwo{} section.
531
532 \textit{Use of \DWFORMstrp{} is not appropriate in a \splitDWARFobjectfile.}
533
534 \needlines{4}
535 \item References to range lists in the \dotdebugranges{} section are
536 all relative to the base offset given by \DWATrangesbase{}
537 in the skeleton compilation unit.
538
539 \item References to relocatable addresses in the object file use
540 the new form code \DWFORMaddrx, referring to slots in the
541 \dotdebugaddr{} table, relative to the base offset given by
542 \DWATaddrbase{} in the skeleton compilation unit.
543 \end{itemize}
544
545 Figure \refersec{fig:splitobjectexampledemo1dwodwarfexcerpts} presents
546 some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
547
548 \begin{figure}[h]
549 \figurepart{1}{2}
550 \begin{dwflisting}
551 \begin{alltt}
552
553     \DWTAGcompileunit
554         \DWATproducer [\DWFORMstrx]: (slot 15) (producer string)
555         \DWATlanguage: \DWLANGCplusplus
556         \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
557         \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
558         \DWATdwoid [\DWFORMdataeight]: 0x44e413b8a2d1b8f
559 1$:   \DWTAGclasstype
560           \DWATname [\DWFORMstrx]: (slot 12) "Point"
561           \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
562           \DWATdeclaration: true
563 2$:     \DWTAGsubprogram
564           \DWATexternal: true
565           \DWATname [\DWFORMstrx]: (slot 12) "Point"
566           \DWATdeclfile: 1
567           \DWATdeclline: 5
568           \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff"
569           \DWATaccessibility: \DWACCESSpublic
570           \DWATdeclaration: true
571         ...
572 3$:   \DWTAGclasstype
573           \DWATname [\DWFORMstring]: "Box"
574           \DWATsignature [\DWFORMrefsigeight]: 0xe97a3917c5a6529b
575           \DWATdeclaration: true
576         ...
577 4$:     \DWTAGsubprogram
578             \DWATexternal: true
579             \DWATname [\DWFORMstrx]: (slot 0) "contains"
580             \DWATdeclfile: 1
581             \DWATdeclline: 28
582             \DWATlinkagename [\DWFORMstrx]: (slot 8) "_ZNK3Box8containsERK5Point"
583             \DWATtype: (reference to 7$)
584             \DWATaccessibility: \DWACCESSpublic
585             \DWATdeclaration: true
586         ...
587 \end{alltt}
588 \end{dwflisting}
589 \caption{Split object example: \texttt{demo1.dwo} excerpts}
590 \label{fig:splitobjectexampledemo1dwodwarfexcerpts}
591 \end{figure}
592         
593 \begin{figure}
594 \figurepart{2}{2}
595 \begin{dwflisting}
596 \begin{alltt}
597
598 5$:   \DWTAGsubprogram
599           \DWATspecification: (reference to 4$)
600           \DWATdeclfile: 2
601           \DWATdeclline: 3
602           \DWATlowpc [\DWFORMaddrx]: (slot 0)
603           \DWAThighpc [\DWFORMdataeight]: 0xbb
604           \DWATframebase: \DWOPcallframecfa
605           \DWATobjectpointer: (reference to 6$)
606 6$:     \DWTAGformalparameter
607             \DWATname [\DWFORMstrx]: (slot 13): "this"
608             \DWATtype: (reference to 8$)
609             \DWATartificial: true
610             \DWATlocation: \DWOPfbreg(-24)
611         \DWTAGformalparameter
612             \DWATname [\DWFORMstring]: "p"
613             \DWATdeclfile: 2
614             \DWATdeclline: 3
615             \DWATtype: (reference to 11$)
616             \DWATlocation: \DWOPfbreg(-32)
617       ...
618 7$:   \DWTAGbasetype
619           \DWATbytesize: 1
620           \DWATencoding: \DWATEboolean
621           \DWATname [\DWFORMstrx]: (slot 5) "bool"
622       ...
623 8$:   \DWTAGconsttype
624           \DWATtype: (reference to 9$)
625 9$:   \DWTAGpointertype
626           \DWATbytesize: 8
627           \DWATtype: (reference to 10$)
628 10$:  \DWTAGconsttype
629           \DWATtype: (reference to 3$)
630       ...
631 11$:  \DWTAGconsttype
632           \DWATtype: (reference to 12$)
633 12$:  \DWTAGreferencetype
634           \DWATbytesize: 8
635           \DWATtype: (reference to 13$)
636 13$:  \DWTAGconsttype
637           \DWATtype: (reference to 1$)
638       ...
639 \end{alltt}
640 \end{dwflisting}
641 \begin{center}
642 \vspace{3mm}
643 Figure~\ref{fig:splitobjectexampledemo1dwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
644 \end{center}
645 \end{figure}
646
647 In the defining declaration for \texttt{Box::contains} at 5\$, the
648 \DWATlowpc{} attribute is represented with \DWFORMaddrx,
649 referring to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
650 That slot contains the relocated address of the beginning of the
651 function.
652
653 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
654 section, and looks like a normal type unit in a non-split object,
655 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
656 attribute that refers to a specialized \dotdebuglinedwo{}
657 \addtoindexx{type unit!specialized \texttt{.debug\_line.dwo} section in}
658 \addtoindexx{specialized \texttt{.debug\_line.dwo} section}
659 section. This
660 section contains a normal line number
661 program header with a list of include directories and filenames,
662 but no line number program. This section is used only as a
663 reference for filenames needed for \DWATdeclfile{} attributes
664 within the type unit.
665
666 The \dotdebugstroffsetsdwo{} section contains an entry for each
667 unique string in the string table. In the \texttt{demo1.dwo} example,
668 these string table slots have been assigned as shown in
669 Figure \refersec{fig:splitobjectexamplestringtableslots}.
670
671 \begin{figure}[H]
672 \begin{center}
673 \small
674 %\footnotesize
675 \begin{tabular}{cl|cl}
676     Slot & String & Slot & String \\
677     \hline
678     0  &   contains                         &    10 &   \_ZNK3Box1rEv \\
679     1  &   \_ZNK5Point1xEv                  &    11 &   \_ZN3BoxC4E5PointS0\_ \\
680     2  &   \_ZNK3Box1lEv                    &    12 &   Point\\
681     3  &   \_ZNK3Box1bEv                    &    13 &   this\\
682     4  &   \textit{(compilation directory)} &    14 &   float \\
683     5  &   bool                             &    15 &   \textit{(producer string)} \\
684     6  &   \_ZN3BoxC4Effff                  &    16 &   \_ZN5PointC4Eff \\
685     7  &   demo1.cc                         &    17 &   \_ZNK3Box1tEv \\
686     8  &   \_ZNK3Box8containsERK5Point      & \\
687     9  &   \_ZNK5Point1yEv                  & \\
688 \end{tabular}
689 \end{center}
690 \caption{Split object example: String table slots}
691 \label{fig:splitobjectexamplestringtableslots}
692 \end{figure}
693
694 Each entry in the table is the offset of the string, which is
695 contained in the \dotdebugstrdwo{} section. 
696
697 In a split DWARF object file, all references to
698 strings go through this table (there are no
699 other offsets to \dotdebugstrdwo{} in a split
700 DWARF object file). That is, there
701 is no use of \DWFORMstrp{} in a split DWARF object file.
702
703 The offsets in these slots have no associated relocations, 
704 because they are not part of a relocatable object file.
705
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 (See Section \refersec{app:dwarfpackagefileexample} 
713 for 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 In \texttt{demo2.dwo} as shown in 
722 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}, 
723 the debugging information for \texttt{Line::clip} describes a local 
724 variable \texttt{slope} whose location varies based on the PC.
725 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts} 
726 presents some excerpts from the \dotdebuginfodwo{} section for 
727 \texttt{demo2.dwo}.
728
729 \begin{figure}[b]
730 \figurepart{1}{2}
731 \begin{dwflisting}
732 \begin{alltt}
733
734 1$: \DWTAGclasstype
735         \DWATname [\DWFORMstrx]: (slot 20) "Line"
736         \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
737         \DWATdeclaration: true
738     ...
739 2$:   \DWTAGsubprogram
740           \DWATexternal: true
741           \DWATname [\DWFORMstrx]: (slot 19) "clip"
742           \DWATdeclfile: 2
743           \DWATdeclline: 16
744           \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
745           \DWATtype: (reference to DIE for bool)
746           \DWATaccessibility: \DWACCESSpublic
747           \DWATdeclaration: true
748       ...
749 \end{alltt}
750 \end{dwflisting}
751 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
752 \label{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}
753 \end{figure}
754
755 \begin{figure}
756 \figurepart{2}{2}
757 \begin{dwflisting}
758 \begin{alltt}
759
760 3$:   \DWTAGsubprogram
761           \DWATspecification: (reference to 2$)
762           \DWATdeclfile: 1
763           \DWATdeclline: 3
764           \DWATlowpc [\DWFORMaddrx]: (slot 32)
765           \DWAThighpc [\DWFORMdataeight]: 0x1ec
766           \DWATframebase: \DWOPcallframecfa
767           \DWATobjectpointer: (reference to 4$)
768 4$:     \DWTAGformalparameter
769             \DWATname: (indexed string: 0x11): this
770             \DWATtype: (reference to DIE for type const Point* const)
771             \DWATartificial: 1
772             \DWATlocation: 0x0 (location list)
773 5$:     \DWTAGformalparameter
774             \DWATname: b
775             \DWATdeclfile: 1
776             \DWATdeclline: 3
777             \DWATtype: (reference to DIE for type const Box& const)
778             \DWATlocation [\DWFORMsecoffset]: 0x2a
779 6$:     \DWTAGlexicalblock
780             \DWATlowpc [\DWFORMaddrx]: (slot 17)
781             \DWAThighpc: 0x1d5
782 7$:       \DWTAGvariable
783               \DWATname [\DWFORMstrx]: (slot 28): "slope"
784               \DWATdeclfile: 1
785               \DWATdeclline: 5
786               \DWATtype: (reference to DIE for type float)
787               \DWATlocation [\DWFORMsecoffset]: 0x49
788
789 \end{alltt}
790 \end{dwflisting}
791 \begin{center}
792 \vspace{3mm}
793 Figure~\ref{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
794 \end{center}
795 \end{figure}
796
797 In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts},
798 The \DWTAGformalparameter{} entries at 4\$ and 5\$ refer to the
799 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
800 \DWTAGvariable{} entry for \texttt{slope} at 7\$ refers to the location
801 list at offset \texttt{0x49}. 
802 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
803 shows a representation of the
804 location lists at those offsets in the \dotdebuglocdwo{} section.
805
806 \begin{figure}
807 \begin{dwflisting}
808 \begin{tabular}{rlrrl}
809 \texttt{offset} & entry type & start & length & expression \\
810 \hline \\
811 0x00 & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfive~(rdi) \\
812 0x09 & \DWLLEstartlengthentry & [11] & 0x01b9 & \DWOPregthree~(rbx) \\
813 0x12 & \DWLLEstartlengthentry & [29] & 0x0003 & \DWOPbregtwelve~(r12):\\
814 &&&& -8; \DWOPstackvalue \\
815 0x1d & \DWLLEstartlengthentry & [31] & 0x0001 & \DWOPentryvalue: \\
816 &&&& (\DWOPregfive~(rdi)); \\
817 &&&& \DWOPstackvalue \\
818 0x29 & \DWLLEendoflistentry &&& \\
819 \\   & \hhline{-} &&& \\
820 0x2a & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfour~(rsi)) \\
821 0x33 & \DWLLEstartlengthentry & [11] & 0x01ba & \DWOPregsix~(rbp)) \\
822 0x3c & \DWLLEstartlengthentry & [30] & 0x0003 & \DWOPentryvalue: \\
823 &&&& (\DWOPregfour~(rsi)); \\
824 &&&& \DWOPstackvalue \\
825 0x48 & \DWLLEendoflistentry &&& \\
826 \\   & \hhline{-} &&& \\
827 0x49 & \DWLLEstartlengthentry & [10] & 0x0004 & \DWOPregeighteen~(xmm1) \\
828 0x52 & \DWLLEstartlengthentry & [11] & 0x01bd & \DWOPfbreg: -36 \\
829 0x5c & \DWLLEendoflistentry &&& \\
830 &&&& \\
831 \end{tabular}
832 \end{dwflisting}
833 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
834 \label{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
835 \end{figure}
836
837 In each \DWLLEstartlengthentry{}, the start field is the index
838 of a slot in the \dotdebugaddr{} section, relative to the base
839 offset defined by the compilations unit's \DWATaddrbase{}
840 attribute. The \dotdebugaddr{} slots referenced by these entries give
841 the relocated address of a label within the function where the
842 address range begins. The length field gives the length of the
843 address range.
844
845 \clearpage
846 \section{DWARF Package File Example}
847 \label{app:dwarfpackagefileexample}
848 \addtoindexx{DWARF duplicate elimination!examples}
849 [TBD]