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