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