dwarf5/latexdoc/splitobjects.tex

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