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