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