d9f4b2fc7e00437188385486d2bef4057c8a246c
[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 new
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{} sections.
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 \end{itemize}
232
233 \needlines{4}
234 Each location list entry contains beginning and ending address
235 offsets, which normally may be relocated addresses. In the
236 \dotdebuglocdwo{} section, these offsets are replaced by indices
237 into the \dotdebugaddr{} section. Each location list entry begins
238 with a single byte identifying the entry type:
239 \begin{itemize}
240 \item
241 \DWLLEendoflistentry{} (0) indicates an end-of-list entry,
242 \item
243 \DWLLEbaseaddressselectionentry{} (1) indicates a base address
244 selection entry, 
245 \item
246 \DWLLEstartendentry{} (2) indicates a normal
247 location list entry providing start and end addresses,
248 \item
249 \DWLLEstartlengthentry{} (3) indicates a normal location list
250 entry providing a start address and a length, and
251 \item
252 \DWLLEoffsetpairentry{} (4) indicates a normal location list
253 entry providing start and end offsets relative to the base
254 address. 
255 \end{itemize}
256 An end-of-list entry has no further data. A base address
257 selection entry contains a single unsigned LEB128
258 \addtoindexx{LEB128!unsigned} number
259 following the entry type byte, which is an index into the
260 \dotdebugaddr{} section that selects the new base address for
261 subsequent location list entries. A start/end entry contains two
262 unsigned LEB128\addtoindexx{LEB128!unsigned} numbers 
263 following the entry type byte, which are
264 indices into the \dotdebugaddr{} section that select the beginning
265 and ending addresses. A start/length entry contains one unsigned
266 LEB128 number and a 4-byte unsigned value (as would be
267 represented by the form code \DWFORMdatafour). The first number
268 is an index into the \dotdebugaddr{} section that selects the
269 beginning offset, and the second number is the length of the
270 range. Addresses fetched from the \dotdebugaddr{} section are not
271 relative to the base address. An offset pair entry contains two
272 4-byte unsigned values (as would be represented by the form code
273 \DWFORMdatafour){}, treated as the beginning and ending offsets,
274 respectively, relative to the base address. As in the \dotdebugloc{}
275 section, the base address is obtained either from the nearest
276 preceding base address selection entry, or, if there is no such
277 entry, from the compilation unit base address (as defined in
278 Section \refersec{chap:normalandpartialcompilationunitentries}). 
279 For the latter three types (start/end,
280 start/length, and offset pair), the two operand values are
281 followed by a location description as in a normal location list
282 entry in the \dotdebugloc{} section.
283
284 \needlines{8}
285 This design depends on having an index of debugging information
286 available to the consumer. For name lookups, the consumer can 
287 use the \dotdebugnames{} index section (see 
288 Section \refersec{chap:acceleratedaccess}) to 
289 locate a skeleton compilation unit. The
290 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
291 compilation unit can then be used to locate the corresponding
292 DWARF object file for the compilation unit. Similarly, for an
293 address lookup, the consumer can use the \dotdebugaranges{} table,
294 which will also lead to a skeleton compilation unit. For a file
295 and line number lookup, the skeleton compilation units can be
296 used to locate the line number tables.
297
298 \section{Split DWARF Object File Example}
299 \label{app:splitdwarfobjectfileexample}
300 \addtoindexx{split DWARF object file!example}
301 Consider the example source code in 
302 Figure \refersec{fig:splitobjectexamplesourcefragment1}, 
303 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
304 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
305 When compiled with split DWARF, we will have two object files,
306 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s}, 
307 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
308
309 \begin{figure}[b]
310 \textit{File demo1.cc}
311 \begin{lstlisting}
312 #include "demo.h"
313
314 bool Box::contains(const Point& p) const
315 {
316     return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
317             p.y() >= ll_.y() && p.y() <= ur_.y());
318 }
319 \end{lstlisting}
320 \caption{Split object example: source fragment \#1}
321 \label{fig:splitobjectexamplesourcefragment1}
322 \end{figure}
323
324 \begin{figure}[h]
325 \textit{File demo2.cc}
326 \begin{lstlisting}
327 #include "demo.h"
328
329 bool Line::clip(const Box& b)
330 {
331   float slope = (end_.y() - start_.y()) / (end_.x() - start_.x());
332   while (1) {
333     // Trivial acceptance.
334     if (b.contains(start_) && b.contains(end_)) return true;
335
336     // Trivial rejection.
337     if (start_.x() < b.l() && end_.x() < b.l()) return false;
338     if (start_.x() > b.r() && end_.x() > b.r()) return false;
339     if (start_.y() < b.b() && end_.y() < b.b()) return false;
340     if (start_.y() > b.t() && end_.y() > b.t()) return false;
341
342     if (b.contains(start_)) {
343       // Swap points so that start_ is outside the clipping 
344       // rectangle.
345       Point temp = start_;
346       start_ = end_;
347       end_ = temp;
348     }
349
350     if (start_.x() < b.l())
351       start_ = Point(b.l(), 
352                      start_.y() + (b.l() - start_.x()) * slope);
353     else if (start_.x() > b.r())
354       start_ = Point(b.r(), 
355                      start_.y() + (b.r() - start_.x()) * slope);
356     else if (start_.y() < b.b())
357       start_ = Point(start_.x() + (b.b() - start_.y()) / slope, 
358                      b.b());
359     else if (start_.y() > b.t())
360       start_ = Point(start_.x() + (b.t() - start_.y()) / slope, 
361                      b.t());
362   }
363 }
364 \end{lstlisting}
365 \caption{Split object example: source fragment \#2}
366 \label{fig:splitobjectexamplesourcefragment2}
367 \end{figure}
368
369 \begin{figure}[h]
370 \textit{File demo.h}
371 \begin{lstlisting}
372 class A {
373   public:
374     Point(float x, float y) : x_(x), y_(y){}
375     float x() const { return x_; }
376     float y() const { return y_; }
377   private:
378     float x_;
379     float y_;
380 };
381
382 class Line {
383   public:
384     Line(Point start, Point end) : start_(start), end_(end){}
385     bool clip(const Box& b);
386     Point start() const { return start_; }
387     Point end() const { return end_; }
388   private:
389     Point start_;
390     Point end_;
391 };
392
393 class Box {
394   public:
395     Box(float l, float r, float b, float t) : ll_(l, b), ur_(r, t){}
396     Box(Point ll, Point ur) : ll_(ll), ur_(ur){}
397     bool contains(const Point& p) const;
398     float l() const { return ll_.x(); }
399     float r() const { return ur_.x(); }
400     float b() const { return ll_.y(); }
401     float t() const { return ur_.y(); }
402   private:
403     Point ll_;
404     Point ur_;
405 };
406
407 \end{lstlisting}
408 \caption{Split object example: source fragment \#3}
409 \label{fig:splitobjectexamplesourcefragment3}
410 \end{figure}
411
412 \clearpage
413 \subsection{Contents of the Object File}
414 The object files each contain the following sections of debug
415 information:
416 \begin{alltt}
417   \dotdebugabbrev
418   \dotdebuginfo
419   \dotdebugranges
420   \dotdebugline
421   \dotdebugstr
422   \dotdebugaddr
423   \dotdebugnames
424   \dotdebugaranges
425 \end{alltt}
426
427 The \dotdebugabbrev{} section contains just a single entry describing
428 the skeleton compilation unit DIE.
429
430 The DWARF description in the \dotdebuginfo{} section 
431 contains just a single DIE, the skeleton compilation unit, 
432 which may look like 
433 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
434
435 \begin{figure}[h]
436 \begin{dwflisting}
437 \begin{alltt}
438
439     \DWTAGcompileunit
440       \DWATcompdir: (reference to directory name in .debug_str)
441       \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
442       \DWATdwoid: 0x44e413b8a2d1b8f
443       \DWATaddrbase: (reference to .debug_addr section)
444       \DWATrangesbase: (reference to range list in .debug_ranges section)
445       \DWATranges: (offset of range list in .debug_ranges section)
446       \DWATstmtlist: (reference to .debug_line section)
447       \DWATlowpc: 0
448       
449 \end{alltt}
450 \end{dwflisting}
451 \caption{Split object example: Skeleton DWARF description}
452 \label{fig:splitdwafexampleskeletondwarfdescription}
453 \end{figure}
454
455 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
456 location of the corresponding \splitDWARFobjectfile{} that
457 contains the full debug information; that file is normally
458 expected to be in the same directory as the object file itself.
459
460 The \DWATdwoid{} attribute provides a hash of the debug
461 information contained in the \splitDWARFobjectfile. This hash 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
465 package file.
466
467 \needlines{4}
468 The \DWATaddrbase{} attribute contains the relocatable offset of
469 this object file's contribution to the \dotdebugaddr{} section, and
470 the \DWATrangesbase{} attribute contains the relocatable offset
471 of this object file's contribution to the \dotdebugranges{} section.
472 The \DWATranges{} attribute refers to a specific range list within
473 that contribution, and its value is a (non-relocatable) offset
474 relative to the base. In a compilation unit with a single
475 contiguous range of code, the \DWATranges{} attribute might be
476 omitted, and instead replaced by the pair \DWATlowpc{} and
477 \DWAThighpc.
478
479 The \DWATstmtlist{} attribute contains the relocatable offset of
480 this file's contribution to the \dotdebugline{} table.
481
482 If there is a \DWATranges{} attribute, the \DWATlowpc{} attribute
483 provides a default base address for the range list entries in the
484 \dotdebugranges{} section. It may be omitted if each range list entry
485 provides an explicit base address selection entry; it may provide
486 a relocatable base address, in which case the offsets in each
487 range list entry are relative to it; or it may have the value 0,
488 in which case the offsets in each range list entry are themselves
489 relocatable addresses.
490
491 The \dotdebugranges{} section contains the range list referenced by
492 the \DWATranges{} attribute in the skeleton compilation unit DIE,
493 plus any range lists referenced by \DWATranges{} attributes in the
494 split DWARF object. In our example, \texttt{demo1.o} would contain range
495 list entries for the function \texttt{Box::contains}, as well as for
496 out-of-line copies of the inline functions \texttt{Point::x} and 
497 \texttt{Point::y}.
498
499 The \dotdebugline{} section contains the full line number table for
500 the compiled code in the object file. In the example in
501 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
502 number program header would list the two files, \texttt{demo.h} and
503 \texttt{demo1.cc}, and would contain line number programs for
504 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
505
506 The \dotdebugstr{} section contains the strings referenced indirectly
507 by the compilation unit DIE and by the line number program.
508
509 The \dotdebugaddr{} section contains relocatable addresses of
510 locations in the loadable text and data that are referenced by
511 debugging information entries in the split DWARF object. In the
512 example in \refersec{fig:splitobjectexamplesourcefragment3}, 
513 \texttt{demo1.o} may have three entries:
514 \begin{center}
515 %\footnotesize
516 \begin{tabular}{cl}
517 Slot & Location referenced \\
518 \hline
519    0   &  low PC value for \texttt{Box::contains}  \\
520    1   &  low PC value for \texttt{Point::x}       \\
521    2   &  low PC value for \texttt{Point::y}       \\
522 \end{tabular}
523 \end{center}
524
525 \needlines{4}
526 The \dotdebugnames{}
527 section contains the names defined by the debugging
528 information in the \splitDWARFobjectfile{} 
529 (see Section \refersec{chap:contentsofthenameindex}, 
530 and references the skeleton compilation unit. 
531 When linked together into a final executable,
532 they can be used by a DWARF consumer to lookup a name to find one
533 or more skeleton compilation units that provide information about
534 that name. From the skeleton compilation unit, the consumer can
535 find the \splitDWARFobjectfile{} that it can then read to get the full
536 DWARF information.
537
538 The \dotdebugaranges{} section contains the PC ranges defined in this
539 compilation unit, and allow a DWARF consumer to map a PC value to
540 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
541
542
543 \subsection{Contents of the Split DWARF Object Files}
544 The \splitDWARFobjectfile{s} each contain the following sections:
545 \begin{alltt}
546   \dotdebugabbrevdwo
547   \dotdebuginfodwo{} (for the compilation unit)
548   \dotdebuginfodwo{} (one COMDAT section for each type unit)
549   \dotdebuglocdwo
550   \dotdebuglinedwo
551   \dotdebugmacrodwo
552   \dotdebugstroffsetsdwo
553   \dotdebugstrdwo
554 \end{alltt}
555 The \dotdebugabbrevdwo{} section contains the abbreviation
556 declarations for the debugging information entries in the
557 \dotdebuginfodwo{} section. In general, it looks just like a normal
558 \dotdebugabbrev{} section in a non-split object file.
559
560 The \dotdebuginfodwo{} section containing the compilation unit
561 contains the full debugging information for the compile unit, and
562 looks much like a normal \dotdebuginfo{} section in a non-split
563 object file, with the following exceptions:
564 \begin{itemize}
565 \item The \DWTAGcompileunit{} DIE does not need to repeat the
566 \DWATranges, \DWATlowpc, \DWAThighpc, and
567 \DWATstmtlist{} attributes that are provided in the skeleton
568 compilation unit.
569
570 \item References to strings in the string table use the new form
571 code \DWFORMstrx, referring to slots in the
572 \dotdebugstroffsetsdwo{} section.
573
574 \textit{Use of \DWFORMstrp{} is not appropriate in a \splitDWARFobjectfile.}
575
576 \needlines{4}
577 \item References to range lists in the \dotdebugranges{} section are
578 all relative to the base offset given by \DWATrangesbase{}
579 in the skeleton compilation unit.
580
581 \item References to relocatable addresses in the object file use
582 the new form code \DWFORMaddrx, referring to slots in the
583 \dotdebugaddr{} table, relative to the base offset given by
584 \DWATaddrbase{} in the skeleton compilation unit.
585 \end{itemize}
586
587 Figure \refersec{fig:splitobjectexampledemo1dwodwarfexcerpts} presents
588 some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
589
590 \begin{figure}[h]
591 \figurepart{1}{2}
592 \begin{dwflisting}
593 \begin{alltt}
594
595     \DWTAGcompileunit
596         \DWATproducer [\DWFORMstrx]: (slot 15) (producer string)
597         \DWATlanguage: \DWLANGCplusplus
598         \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
599         \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
600         \DWATdwoid [\DWFORMdataeight]: 0x44e413b8a2d1b8f
601 1$:   \DWTAGclasstype
602           \DWATname [\DWFORMstrx]: (slot 12) "Point"
603           \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
604           \DWATdeclaration: true
605 2$:     \DWTAGsubprogram
606           \DWATexternal: true
607           \DWATname [\DWFORMstrx]: (slot 12) "Point"
608           \DWATdeclfile: 1
609           \DWATdeclline: 5
610           \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff"
611           \DWATaccessibility: \DWACCESSpublic
612           \DWATdeclaration: true
613         ...
614 3$:   \DWTAGclasstype
615           \DWATname [\DWFORMstring]: "Box"
616           \DWATsignature [\DWFORMrefsigeight]: 0xe97a3917c5a6529b
617           \DWATdeclaration: true
618         ...
619 4$:     \DWTAGsubprogram
620             \DWATexternal: true
621             \DWATname [\DWFORMstrx]: (slot 0) "contains"
622             \DWATdeclfile: 1
623             \DWATdeclline: 28
624             \DWATlinkagename [\DWFORMstrx]: (slot 8) "_ZNK3Box8containsERK5Point"
625             \DWATtype: (reference to 7$)
626             \DWATaccessibility: \DWACCESSpublic
627             \DWATdeclaration: true
628         ...
629 \end{alltt}
630 \end{dwflisting}
631 \caption{Split object example: \texttt{demo1.dwo} excerpts}
632 \label{fig:splitobjectexampledemo1dwodwarfexcerpts}
633 \end{figure}
634         
635 \begin{figure}
636 \figurepart{2}{2}
637 \begin{dwflisting}
638 \begin{alltt}
639
640 5$:   \DWTAGsubprogram
641           \DWATspecification: (reference to 4$)
642           \DWATdeclfile: 2
643           \DWATdeclline: 3
644           \DWATlowpc [\DWFORMaddrx]: (slot 0)
645           \DWAThighpc [\DWFORMdataeight]: 0xbb
646           \DWATframebase: \DWOPcallframecfa
647           \DWATobjectpointer: (reference to 6$)
648 6$:     \DWTAGformalparameter
649             \DWATname [\DWFORMstrx]: (slot 13): "this"
650             \DWATtype: (reference to 8$)
651             \DWATartificial: true
652             \DWATlocation: \DWOPfbreg(-24)
653         \DWTAGformalparameter
654             \DWATname [\DWFORMstring]: "p"
655             \DWATdeclfile: 2
656             \DWATdeclline: 3
657             \DWATtype: (reference to 11$)
658             \DWATlocation: \DWOPfbreg(-32)
659       ...
660 7$:   \DWTAGbasetype
661           \DWATbytesize: 1
662           \DWATencoding: \DWATEboolean
663           \DWATname [\DWFORMstrx]: (slot 5) "bool"
664       ...
665 8$:   \DWTAGconsttype
666           \DWATtype: (reference to 9$)
667 9$:   \DWTAGpointertype
668           \DWATbytesize: 8
669           \DWATtype: (reference to 10$)
670 10$:  \DWTAGconsttype
671           \DWATtype: (reference to 3$)
672       ...
673 11$:  \DWTAGconsttype
674           \DWATtype: (reference to 12$)
675 12$:  \DWTAGreferencetype
676           \DWATbytesize: 8
677           \DWATtype: (reference to 13$)
678 13$:  \DWTAGconsttype
679           \DWATtype: (reference to 1$)
680       ...
681 \end{alltt}
682 \end{dwflisting}
683 \begin{center}
684 \vspace{3mm}
685 Figure~\ref{fig:splitobjectexampledemo1dwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
686 \end{center}
687 \end{figure}
688
689 In the defining declaration for \texttt{Box::contains} at 5\$, the
690 \DWATlowpc{} attribute is represented with \DWFORMaddrx,
691 referring to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
692 That slot contains the relocated address of the beginning of the
693 function.
694
695 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
696 section, and looks like a normal type unit in a non-split object,
697 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
698 attribute that refers to a specialized \dotdebuglinedwo{}
699 \addtoindexx{type unit!specialized \texttt{.debug\_line.dwo} section in}
700 \addtoindexx{specialized \texttt{.debug\_line.dwo} section}
701 section. This
702 section contains a normal line number
703 program header with a list of include directories and filenames,
704 but no line number program. This section is used only as a
705 reference for filenames needed for \DWATdeclfile{} attributes
706 within the type unit.
707
708 The \dotdebugstroffsetsdwo{} section contains an entry for each
709 unique string in the string table. In the \texttt{demo1.dwo} example,
710 these string table slots have been assigned as shown in
711 Figure \refersec{fig:splitobjectexamplestringtableslots}.
712
713 \begin{figure}[H]
714 \begin{center}
715 \small
716 %\footnotesize
717 \begin{tabular}{cl|cl}
718     Slot & String & Slot & String \\
719     \hline
720     0  &   contains                         &    10 &   \_ZNK3Box1rEv \\
721     1  &   \_ZNK5Point1xEv                  &    11 &   \_ZN3BoxC4E5PointS0\_ \\
722     2  &   \_ZNK3Box1lEv                    &    12 &   Point\\
723     3  &   \_ZNK3Box1bEv                    &    13 &   this\\
724     4  &   \textit{(compilation directory)} &    14 &   float \\
725     5  &   bool                             &    15 &   \textit{(producer string)} \\
726     6  &   \_ZN3BoxC4Effff                  &    16 &   \_ZN5PointC4Eff \\
727     7  &   demo1.cc                         &    17 &   \_ZNK3Box1tEv \\
728     8  &   \_ZNK3Box8containsERK5Point      & \\
729     9  &   \_ZNK5Point1yEv                  & \\
730 \end{tabular}
731 \end{center}
732 \caption{Split object example: String table slots}
733 \label{fig:splitobjectexamplestringtableslots}
734 \end{figure}
735
736 Each entry in the table is the offset of the string, which is
737 contained in the \dotdebugstrdwo{} section. 
738
739 In a split DWARF object file, all references to
740 strings go through this table (there are no
741 other offsets to \dotdebugstrdwo{} in a split
742 DWARF object file). That is, there
743 is no use of \DWFORMstrp{} in a split DWARF object file.
744
745 The offsets in these slots have no associated relocations, 
746 because they are not part of a relocatable object file.
747
748 When combined into a DWARF package file, however, each 
749 slot must be adjusted to refer to the appropriate offset 
750 within the merged string table (\dotdebugstrdwo{}).
751 The tool that builds the DWARF package file must understand 
752 the structure of the \dotdebugstroffsetsdwo{} section in 
753 order to apply the necessary adjustments. 
754 (See Section \refersec{app:dwarfpackagefileexample} 
755 for an example of a DWARF package file.)
756
757 \needlines{4}
758 The \dotdebuglocdwo{} section contains the location lists referenced
759 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
760 section has a similar format to the \dotdebugloc{} section in a
761 non-split object, but it has some small differences as explained
762 in Section \refersec{datarep:locationlistentriesinsplitobjects}. 
763 In \texttt{demo2.dwo} as shown in 
764 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}, 
765 the debugging information for \texttt{Line::clip} describes a local 
766 variable \texttt{slope} whose location varies based on the PC.
767 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts} 
768 presents some excerpts from the \dotdebuginfodwo{} section for 
769 \texttt{demo2.dwo}.
770
771 \begin{figure}[b]
772 \figurepart{1}{2}
773 \begin{dwflisting}
774 \begin{alltt}
775
776 1$: \DWTAGclasstype
777         \DWATname [\DWFORMstrx]: (slot 20) "Line"
778         \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
779         \DWATdeclaration: true
780     ...
781 2$:   \DWTAGsubprogram
782           \DWATexternal: true
783           \DWATname [\DWFORMstrx]: (slot 19) "clip"
784           \DWATdeclfile: 2
785           \DWATdeclline: 16
786           \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
787           \DWATtype: (reference to DIE for bool)
788           \DWATaccessibility: \DWACCESSpublic
789           \DWATdeclaration: true
790       ...
791 \end{alltt}
792 \end{dwflisting}
793 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
794 \label{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}
795 \end{figure}
796
797 \begin{figure}
798 \figurepart{2}{2}
799 \begin{dwflisting}
800 \begin{alltt}
801
802 3$:   \DWTAGsubprogram
803           \DWATspecification: (reference to 2$)
804           \DWATdeclfile: 1
805           \DWATdeclline: 3
806           \DWATlowpc [\DWFORMaddrx]: (slot 32)
807           \DWAThighpc [\DWFORMdataeight]: 0x1ec
808           \DWATframebase: \DWOPcallframecfa
809           \DWATobjectpointer: (reference to 4$)
810 4$:     \DWTAGformalparameter
811             \DWATname: (indexed string: 0x11): this
812             \DWATtype: (reference to DIE for type const Point* const)
813             \DWATartificial: 1
814             \DWATlocation: 0x0 (location list)
815 5$:     \DWTAGformalparameter
816             \DWATname: b
817             \DWATdeclfile: 1
818             \DWATdeclline: 3
819             \DWATtype: (reference to DIE for type const Box& const)
820             \DWATlocation [\DWFORMsecoffset]: 0x2a
821 6$:     \DWTAGlexicalblock
822             \DWATlowpc [\DWFORMaddrx]: (slot 17)
823             \DWAThighpc: 0x1d5
824 7$:       \DWTAGvariable
825               \DWATname [\DWFORMstrx]: (slot 28): "slope"
826               \DWATdeclfile: 1
827               \DWATdeclline: 5
828               \DWATtype: (reference to DIE for type float)
829               \DWATlocation [\DWFORMsecoffset]: 0x49
830
831 \end{alltt}
832 \end{dwflisting}
833 \begin{center}
834 \vspace{3mm}
835 Figure~\ref{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
836 \end{center}
837 \end{figure}
838
839 In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts},
840 The \DWTAGformalparameter{} entries at 4\$ and 5\$ refer to the
841 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
842 \DWTAGvariable{} entry for \texttt{slope} at 7\$ refers to the location
843 list at offset \texttt{0x49}. 
844 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
845 shows a representation of the
846 location lists at those offsets in the \dotdebuglocdwo{} section.
847
848 \begin{figure}
849 \begin{dwflisting}
850 \begin{tabular}{rlrrl}
851 \texttt{offset} & entry type & start & length & expression \\
852 \hline \\
853 0x00 & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfive~(rdi) \\
854 0x09 & \DWLLEstartlengthentry & [11] & 0x01b9 & \DWOPregthree~(rbx) \\
855 0x12 & \DWLLEstartlengthentry & [29] & 0x0003 & \DWOPbregtwelve~(r12):\\
856 &&&& -8; \DWOPstackvalue \\
857 0x1d & \DWLLEstartlengthentry & [31] & 0x0001 & \DWOPentryvalue: \\
858 &&&& (\DWOPregfive~(rdi)); \\
859 &&&& \DWOPstackvalue \\
860 0x29 & \DWLLEendoflistentry &&& \\
861 \\   & \hhline{-} &&& \\
862 0x2a & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfour~(rsi)) \\
863 0x33 & \DWLLEstartlengthentry & [11] & 0x01ba & \DWOPregsix~(rbp)) \\
864 0x3c & \DWLLEstartlengthentry & [30] & 0x0003 & \DWOPentryvalue: \\
865 &&&& (\DWOPregfour~(rsi)); \\
866 &&&& \DWOPstackvalue \\
867 0x48 & \DWLLEendoflistentry &&& \\
868 \\   & \hhline{-} &&& \\
869 0x49 & \DWLLEstartlengthentry & [10] & 0x0004 & \DWOPregeighteen~(xmm1) \\
870 0x52 & \DWLLEstartlengthentry & [11] & 0x01bd & \DWOPfbreg: -36 \\
871 0x5c & \DWLLEendoflistentry &&& \\
872 &&&& \\
873 \end{tabular}
874 \end{dwflisting}
875 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
876 \label{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
877 \end{figure}
878
879 In each \DWLLEstartlengthentry{}, the start field is the index
880 of a slot in the \dotdebugaddr{} section, relative to the base
881 offset defined by the compilations unit's \DWATaddrbase{}
882 attribute. The \dotdebugaddr{} slots referenced by these entries give
883 the relocated address of a label within the function where the
884 address range begins. The length field gives the length of the
885 address range.
886
887 \clearpage
888 \section{DWARF Package File Example}
889 \label{app:dwarfpackagefileexample}
890 \addtoindexx{DWARF duplicate elimination!examples}
891 [TBD]