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