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 new
  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
  46 \needlines{4}
  47 The optional set of debugging sections includes the following:
  48 \begin{itemize}
  49 \item
  50 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
  51 \DWTAGtypeunit{} DIEs and
  52 their descendants. This is the bulk of the debugging
  53 information for the compilation unit that is normally found
  54 in the \dotdebuginfo{} section.
  55 \item
  56 \dotdebugabbrevdwo{} - Contains the abbreviations tables used by
  57 the \dotdebuginfodwo{} sections.
  58 \item
  59 \dotdebuglocdwo{} - Contains the location lists referenced by
  60 the debugging information entries in the \dotdebuginfodwo{}
  61 section. This contains the location lists normally found in
  62 the \dotdebugloc{} section,
  63 with a slightly modified format to eliminate the need for
  64 relocations.
  65 \item
  66 \dotdebugstrdwo{} - Contains the string table for all indirect
  67 strings referenced by the debugging information in the
  68 \dotdebuginfodwo{} sections.
  69 \item
  70 \dotdebugstroffsetsdwo{} - Contains the string offsets table
  71 for the strings in the \dotdebugstrdwo{}{} section.
  72 \item
  73 \dotdebugmacrodwo{} - Contains macro definition information,
  74 normally found in the \dotdebugmacro{} section.
  75 \item
  76 \dotdebuglinedwo{} - Contains \addtoindex{specialized line number table}s
  77 for the type units in the \dotdebuginfodwo{} section. These tables
  78 contain only the directory and filename lists needed to
  79 interpret \DWATdeclfile{} attributes in the debugging
  80 information entries. Actual line number tables remain in the
  81 \dotdebugline{} section, and remain in the relocatable object
  82 (.o) files.
  83
  84 \end{itemize}
  85
  86 In a .dwo file there is no benefit to having a separate string
  87 section for directories and file names because the primary
  88 string table will never be stripped. Accordingly, no
  89 \texttt{.debug\_line\_str.dwo} is defined. Content descriptions corresponding
  90 to \DWFORMlinestrp{} in an executable file (for example, in the
  91 skeleton compilation unit) instead use \DWFORMstrx. This allows
  92 directory and file name strings to be merged with general
  93 strings and across compilations in package files (which are not
  94 subject to potential stripping).
  95
  96
  97
  98 In order for the consumer to locate and process the debug
  99 information, the compiler must produce a small amount of debug
 100 information that passes through the linker into the output
 101 binary. A skeleton \dotdebuginfo{} section for each compilation unit
 102 contains a reference to the corresponding \texttt{.o} or \texttt{.dwo}
 103 file, and the \dotdebugline{} section (which is typically small
 104 compared to the \dotdebuginfo{} sections) is
 105 linked into the output binary, as is the new \dotdebugaddr{}
 106 section.
 107
 108 \needlines{6}
 109 The debug sections that continue to be linked into the
 110 output binary include the following:
 111 \begin{itemize}
 112 \item
 113 \dotdebugabbrev{} - Contains the abbreviation codes used by the
 114 skeleton \dotdebuginfo{} section.
 115 \item
 116 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
 117 but no children.
 118 \item
 119 \dotdebugstr{} - Contains any strings referenced by the skeleton
 120 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
 121 \item
 122 \dotdebugstroffsets{} - Contains the string offsets table for
 123 the strings in the \dotdebugstr{} section.
 124 \item
 125 \dotdebugaddr{} - Contains references to loadable sections,
 126 indexed by attributes of form \DWFORMaddrx{} or location
 127 expression \DWOPaddrx{} opcodes.
 128 \item
 129 \dotdebugline{} - Contains the line number tables, unaffected by
 130 this design. (These could be moved to the .dwo file, but in
 131 order to do so, each \DWLNEsetaddress{} opcode would need to
 132 be replaced by a new opcode that referenced an entry in the
 133 \dotdebugaddr{} section. Furthermore, leaving this section in the
 134 .o file allows many debug info consumers to remain unaware of
 135 .dwo files.)
 136 \item
 137 \dotdebugframe{} - Contains the frame tables, unaffected by this
 138 design.
 139 \item
 140 \dotdebugranges{} - Contains the range lists, unaffected by this
 141 design.
 142 \item
 143 \dotdebugnames{} - Contains the names for use in
 144 building an index section. This section has the same
 145 format and use as always. The section header refers to a
 146 compilation unit offset, which is the offset of the
 147 skeleton compilation unit in the \dotdebuginfo{} section.
 148 \item
 149 \dotdebugaranges{} - Contains the accelerated range lookup table
 150 for the compilation unit, unaffected by this design.
 151 \end{itemize}
 152
 153 \needlines{6}
 154 The skeleton \DWTAGcompileunit{} DIE has the following attributes:
 155 \autocols[0pt]{c}{3}{l}{
 156 \DWATaddrbase{},
 157 \DWATcompdir{},
 158 \DWATdwoname{},
 159 \DWATdwoid{},
 160 \DWAThighpc{} \dag,
 161 \DWATlowpc{} \dag,
 162 \DWATranges{} \dag,
 163 \DWATrangesbase{},
 164 \DWATstmtlist{},
 165 \DWATstroffsetsbase{}
 166 }
 167 \dag{} If \DWATranges{} is present, the \DWATlowpc{}/\DWAThighpc{}
 168 pair is not used, although \DWATlowpc{} may still be present
 169 to provide a default base address for range list entries.
 170 Conversely, if the \DWATlowpc/\linebreak[0]\DWAThighpc{} pair is
 171 present, then \DWATranges{} is not used.
 172
 173 All other attributes of the compilation unit DIE are moved to
 174 the full DIE in the \dotdebuginfodwo{} section.
 175 The \DWATdwoid{} attribute is present
 176 in both the skeleton DIE and the full DIE, so that a consumer
 177 can verify a match.
 178
 179 \needlines{4}
 180 Because of other improvements in \DWARFVersionV, most of the
 181 relocations that would normally be found in the \dotdebuginfodwo{}
 182 sections are moved to the \dotdebugaddr{} and
 183 \dotdebugstroffsetsdwo{} sections. Those in the
 184 \dotdebugstroffsetsdwo{} sections are simply omitted because the
 185 DWARF information in those sections is not combined at link
 186 time, so no relocation is necessary. Similarly,
 187 many of the remaining relocations referring to range lists are
 188 eliminated.
 189
 190 The relocations that remain fall into the following categories:
 191 \begin{itemize}
 192 \item
 193 References from compilation unit and type unit headers to the
 194 \dotdebugabbrevdwo{} section. Because the new sections are not
 195 combined at link time, these references need no relocations.
 196 \item
 197 References from \DWTAGcompileunit{} DIEs to the
 198 \dotdebuglinedwo{} section, via \DWATstmtlist{}. This attribute
 199 remains in the skeleton \dotdebuginfo{} section, so no
 200 relocation in the \dotdebuginfodwo{} section is necessary.
 201 \item
 202 References from \DWTAGtypeunit{} DIEs to the skeleton
 203 \dotdebuglinedwo{} section, via \DWATstmtlist{}. Because the new
 204 sections are not combined at link time, these references need
 205 no relocations.
 206 \item
 207 References from \DWTAGcompileunit{} and \DWTAGtypeunit{} DIEs
 208 to the \dotdebugstroffsetsdwo{} section, via
 209 \DWATstroffsetsbase{}. Because the new sections are not
 210 combined at link time, the \DWATstroffsetsbase{} attribute
 211 is not required in a \dotdebuginfodwo{}
 212 section.
 213 \item
 214 References from \DWTAGcompileunit{} DIEs to the \dotdebugaddr{}
 215 section, via \DWATaddrbase{}. This attribute remains in
 216 the skeleton \dotdebuginfo{} section, so no relocation in the
 217 \dotdebuginfodwo{} section is necessary.
 218 \needlines{4}
 219 \item
 220 References from \DWTAGcompileunit{} DIEs to the \dotdebugranges{}
 221 section, via \DWATrangesbase{}. This attribute remains in
 222 the skeleton \dotdebuginfo{} section, so no relocation in the
 223 \dotdebuginfodwo{} section is necessary.
 224 \item
 225 References from the \dotdebuglocdwo{} section to machine addresses
 226 via a location list entry or a base address selection entry.
 227 With a minor change to the location list entry format,
 228 described below, these relocations are also eliminated.
 229 \end{itemize}
 230
 231 \needlines{4}
 232 Each location list entry contains beginning and ending address
 233 offsets, which normally may be relocated addresses. In the
 234 \dotdebuglocdwo{} section, these offsets are replaced by indices
 235 into the \dotdebugaddr{} section. Each location list entry begins
 236 with a single byte identifying the entry type:
 237 \begin{itemize}
 238 \item
 239 \DWLLEendoflistentry{} (0) indicates an end-of-list entry,
 240 \item
 241 \DWLLEbaseaddressselectionentry{} (1) indicates a base address
 242 selection entry,
 243 \item
 244 \DWLLEstartendentry{} (2) indicates a normal
 245 location list entry providing start and end addresses,
 246 \item
 247 \DWLLEstartlengthentry{} (3) indicates a normal location list
 248 entry providing a start address and a length, and
 249 \item
 250 \DWLLEoffsetpairentry{} (4) indicates a normal location list
 251 entry providing start and end offsets relative to the base
 252 address.
 253 \end{itemize}
 254 An end-of-list entry has no further data. A base address
 255 selection entry contains a single unsigned LEB128
 256 \addtoindexx{LEB128!unsigned} number
 257 following the entry type byte, which is an index into the
 258 \dotdebugaddr{} section that selects the new base address for
 259 subsequent location list entries. A start/end entry contains two
 260 unsigned LEB128\addtoindexx{LEB128!unsigned} numbers
 261 following the entry type byte, which are
 262 indices into the \dotdebugaddr{} section that select the beginning
 263 and ending addresses. A start/length entry contains one unsigned
 264 LEB128 number and a 4-byte unsigned value (as would be
 265 represented by the form code \DWFORMdatafour). The first number
 266 is an index into the \dotdebugaddr{} section that selects the
 267 beginning offset, and the second number is the length of the
 268 range. Addresses fetched from the \dotdebugaddr{} section are not
 269 relative to the base address. An offset pair entry contains two
 270 4-byte unsigned values (as would be represented by the form code
 271 \DWFORMdatafour){}, treated as the beginning and ending offsets,
 272 respectively, relative to the base address. As in the \dotdebugloc{}
 273 section, the base address is obtained either from the nearest
 274 preceding base address selection entry, or, if there is no such
 275 entry, from the compilation unit base address (as defined in
 276 Section \refersec{chap:normalandpartialcompilationunitentries}).
 277 For the latter three types (start/end,
 278 start/length, and offset pair), the two operand values are
 279 followed by a location description as in a normal location list
 280 entry in the \dotdebugloc{} section.
 281
 282 \needlines{8}
 283 This design depends on having an index of debugging information
 284 available to the consumer. For name lookups, the consumer can
 285 use the \dotdebugnames{} index section (see
 286 Section \refersec{chap:acceleratedaccess}) to
 287 locate a skeleton compilation unit. The
 288 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
 289 compilation unit can then be used to locate the corresponding
 290 DWARF object file for the compilation unit. Similarly, for an
 291 address lookup, the consumer can use the \dotdebugaranges{} table,
 292 which will also lead to a skeleton compilation unit. For a file
 293 and line number lookup, the skeleton compilation units can be
 294 used to locate the line number tables.
 295
 296 \section{Split DWARF Object File Example}
 297 \label{app:splitdwarfobjectfileexample}
 298 \addtoindexx{split DWARF object file!example}
 299 Consider the example source code in
 300 Figure \refersec{fig:splitobjectexamplesourcefragment1},
 301 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
 302 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
 303 When compiled with split DWARF, we will have two object files,
 304 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s},
 305 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
 306
 307 \begin{figure}[b]
 308 \textit{File demo1.cc}
 309 \begin{lstlisting}
 310 #include "demo.h"
 311
 312 bool Box::contains(const Point& p) const
 313 {
 314     return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
 315             p.y() >= ll_.y() && p.y() <= ur_.y());
 316 }
 317 \end{lstlisting}
 318 \caption{Split object example: source fragment \#1}
 319 \label{fig:splitobjectexamplesourcefragment1}
 320 \end{figure}
 321
 322 \begin{figure}[h]
 323 \textit{File demo2.cc}
 324 \begin{lstlisting}
 325 #include "demo.h"
 326
 327 bool Line::clip(const Box& b)
 328 {
 329   float slope = (end_.y() - start_.y()) / (end_.x() - start_.x());
 330   while (1) {
 331     // Trivial acceptance.
 332     if (b.contains(start_) && b.contains(end_)) return true;
 333
 334     // Trivial rejection.
 335     if (start_.x() < b.l() && end_.x() < b.l()) return false;
 336     if (start_.x() > b.r() && end_.x() > b.r()) return false;
 337     if (start_.y() < b.b() && end_.y() < b.b()) return false;
 338     if (start_.y() > b.t() && end_.y() > b.t()) return false;
 339
 340     if (b.contains(start_)) {
 341       // Swap points so that start_ is outside the clipping
 342       // rectangle.
 343       Point temp = start_;
 344       start_ = end_;
 345       end_ = temp;
 346     }
 347
 348     if (start_.x() < b.l())
 349       start_ = Point(b.l(),
 350                      start_.y() + (b.l() - start_.x()) * slope);
 351     else if (start_.x() > b.r())
 352       start_ = Point(b.r(),
 353                      start_.y() + (b.r() - start_.x()) * slope);
 354     else if (start_.y() < b.b())
 355       start_ = Point(start_.x() + (b.b() - start_.y()) / slope,
 356                      b.b());
 357     else if (start_.y() > b.t())
 358       start_ = Point(start_.x() + (b.t() - start_.y()) / slope,
 359                      b.t());
 360   }
 361 }
 362 \end{lstlisting}
 363 \caption{Split object example: source fragment \#2}
 364 \label{fig:splitobjectexamplesourcefragment2}
 365 \end{figure}
 366
 367 \begin{figure}[h]
 368 \textit{File demo.h}
 369 \begin{lstlisting}
 370 class A {
 371   public:
 372     Point(float x, float y) : x_(x), y_(y){}
 373     float x() const { return x_; }
 374     float y() const { return y_; }
 375   private:
 376     float x_;
 377     float y_;
 378 };
 379
 380 class Line {
 381   public:
 382     Line(Point start, Point end) : start_(start), end_(end){}
 383     bool clip(const Box& b);
 384     Point start() const { return start_; }
 385     Point end() const { return end_; }
 386   private:
 387     Point start_;
 388     Point end_;
 389 };
 390
 391 class Box {
 392   public:
 393     Box(float l, float r, float b, float t) : ll_(l, b), ur_(r, t){}
 394     Box(Point ll, Point ur) : ll_(ll), ur_(ur){}
 395     bool contains(const Point& p) const;
 396     float l() const { return ll_.x(); }
 397     float r() const { return ur_.x(); }
 398     float b() const { return ll_.y(); }
 399     float t() const { return ur_.y(); }
 400   private:
 401     Point ll_;
 402     Point ur_;
 403 };
 404
 405 \end{lstlisting}
 406 \caption{Split object example: source fragment \#3}
 407 \label{fig:splitobjectexamplesourcefragment3}
 408 \end{figure}
 409
 410 \clearpage
 411 \subsection{Contents of the Object File}
 412 The object files each contain the following sections of debug
 413 information:
 414 \begin{alltt}
 415   \dotdebugabbrev
 416   \dotdebuginfo
 417   \dotdebugranges
 418   \dotdebugline
 419   \dotdebugstr
 420   \dotdebugaddr
 421   \dotdebugnames
 422   \dotdebugaranges
 423 \end{alltt}
 424
 425 The \dotdebugabbrev{} section contains just a single entry describing
 426 the skeleton compilation unit DIE.
 427
 428 The DWARF description in the \dotdebuginfo{} section
 429 contains just a single DIE, the skeleton compilation unit,
 430 which may look like
 431 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
 432
 433 \begin{figure}[h]
 434 \begin{dwflisting}
 435 \begin{alltt}
 436
 437     \DWTAGcompileunit
 438       \DWATcompdir: (reference to directory name in .debug_str)
 439       \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
 440       \DWATdwoid: 0x44e413b8a2d1b8f
 441       \DWATaddrbase: (reference to .debug_addr section)
 442       \DWATrangesbase: (reference to range list in .debug_ranges section)
 443       \DWATranges: (offset of range list in .debug_ranges section)
 444       \DWATstmtlist: (reference to .debug_line section)
 445       \DWATlowpc: 0
 446
 447 \end{alltt}
 448 \end{dwflisting}
 449 \caption{Split object example: Skeleton DWARF description}
 450 \label{fig:splitdwafexampleskeletondwarfdescription}
 451 \end{figure}
 452
 453 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
 454 location of the corresponding \splitDWARFobjectfile{} that
 455 contains the full debug information; that file is normally
 456 expected to be in the same directory as the object file itself.
 457
 458 The \DWATdwoid{} attribute provides a hash of the debug
 459 information contained in the \splitDWARFobjectfile. This hash serves
 460 two purposes: it can be used to verify that the debug information
 461 in the \splitDWARFobjectfile{} matches the information in the object
 462 file, and it can be used to find the debug information in a DWARF
 463 package file.
 464
 465 \needlines{4}
 466 The \DWATaddrbase{} attribute contains the relocatable offset of
 467 this object file's contribution to the \dotdebugaddr{} section, and
 468 the \DWATrangesbase{} attribute contains the relocatable offset
 469 of this object file's contribution to the \dotdebugranges{} section.
 470 The \DWATranges{} attribute refers to a specific range list within
 471 that contribution, and its value is a (non-relocatable) offset
 472 relative to the base. In a compilation unit with a single
 473 contiguous range of code, the \DWATranges{} attribute might be
 474 omitted, and instead replaced by the pair \DWATlowpc{} and
 475 \DWAThighpc.
 476
 477 The \DWATstmtlist{} attribute contains the relocatable offset of
 478 this file's contribution to the \dotdebugline{} table.
 479
 480 If there is a \DWATranges{} attribute, the \DWATlowpc{} attribute
 481 provides a default base address for the range list entries in the
 482 \dotdebugranges{} section. It may be omitted if each range list entry
 483 provides an explicit base address selection entry; it may provide
 484 a relocatable base address, in which case the offsets in each
 485 range list entry are relative to it; or it may have the value 0,
 486 in which case the offsets in each range list entry are themselves
 487 relocatable addresses.
 488
 489 The \dotdebugranges{} section contains the range list referenced by
 490 the \DWATranges{} attribute in the skeleton compilation unit DIE,
 491 plus any range lists referenced by \DWATranges{} attributes in the
 492 split DWARF object. In our example, \texttt{demo1.o} would contain range
 493 list entries for the function \texttt{Box::contains}, as well as for
 494 out-of-line copies of the inline functions \texttt{Point::x} and
 495 \texttt{Point::y}.
 496
 497 The \dotdebugline{} section contains the full line number table for
 498 the compiled code in the object file. In the example in
 499 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
 500 number program header would list the two files, \texttt{demo.h} and
 501 \texttt{demo1.cc}, and would contain line number programs for
 502 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
 503
 504 The \dotdebugstr{} section contains the strings referenced indirectly
 505 by the compilation unit DIE and by the line number program.
 506
 507 The \dotdebugaddr{} section contains relocatable addresses of
 508 locations in the loadable text and data that are referenced by
 509 debugging information entries in the split DWARF object. In the
 510 example in \refersec{fig:splitobjectexamplesourcefragment3},
 511 \texttt{demo1.o} may have three entries:
 512 \begin{center}
 513 %\footnotesize
 514 \begin{tabular}{cl}
 515 Slot & Location referenced \\
 516 \hline
 517    0   &  low PC value for \texttt{Box::contains}  \\
 518    1   &  low PC value for \texttt{Point::x}       \\
 519    2   &  low PC value for \texttt{Point::y}       \\
 520 \end{tabular}
 521 \end{center}
 522
 523 \needlines{4}
 524 The \dotdebugnames{}
 525 section contains the names defined by the debugging
 526 information in the \splitDWARFobjectfile{}
 527 (see Section \refersec{chap:contentsofthenameindex},
 528 and references the skeleton compilation unit.
 529 When linked together into a final executable,
 530 they can be used by a DWARF consumer to lookup a name to find one
 531 or more skeleton compilation units that provide information about
 532 that name. From the skeleton compilation unit, the consumer can
 533 find the \splitDWARFobjectfile{} that it can then read to get the full
 534 DWARF information.
 535
 536 The \dotdebugaranges{} section contains the PC ranges defined in this
 537 compilation unit, and allow a DWARF consumer to map a PC value to
 538 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
 539
 540
 541 \subsection{Contents of the Split DWARF Object Files}
 542 The \splitDWARFobjectfile{s} each contain the following sections:
 543 \begin{alltt}
 544   \dotdebugabbrevdwo
 545   \dotdebuginfodwo{} (for the compilation unit)
 546   \dotdebuginfodwo{} (one COMDAT section for each type unit)
 547   \dotdebuglocdwo
 548   \dotdebuglinedwo
 549   \dotdebugmacrodwo
 550   \dotdebugstroffsetsdwo
 551   \dotdebugstrdwo
 552 \end{alltt}
 553 The \dotdebugabbrevdwo{} section contains the abbreviation
 554 declarations for the debugging information entries in the
 555 \dotdebuginfodwo{} section. In general, it looks just like a normal
 556 \dotdebugabbrev{} section in a non-split object file.
 557
 558 The \dotdebuginfodwo{} section containing the compilation unit
 559 contains the full debugging information for the compile unit, and
 560 looks much like a normal \dotdebuginfo{} section in a non-split
 561 object file, with the following exceptions:
 562 \begin{itemize}
 563 \item The \DWTAGcompileunit{} DIE does not need to repeat the
 564 \DWATranges, \DWATlowpc, \DWAThighpc, and
 565 \DWATstmtlist{} attributes that are provided in the skeleton
 566 compilation unit.
 567
 568 \item References to strings in the string table use the new form
 569 code \DWFORMstrx, referring to slots in the
 570 \dotdebugstroffsetsdwo{} section.
 571
 572 \textit{Use of \DWFORMstrp{} is not appropriate in a \splitDWARFobjectfile.}
 573
 574 \needlines{4}
 575 \item References to range lists in the \dotdebugranges{} section are
 576 all relative to the base offset given by \DWATrangesbase{}
 577 in the skeleton compilation unit.
 578
 579 \item References to relocatable addresses in the object file use
 580 the new form code \DWFORMaddrx, referring to slots in the
 581 \dotdebugaddr{} table, relative to the base offset given by
 582 \DWATaddrbase{} in the skeleton compilation unit.
 583 \end{itemize}
 584
 585 Figure \refersec{fig:splitobjectexampledemo1dwodwarfexcerpts} presents
 586 some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
 587
 588 \begin{figure}[h]
 589 \figurepart{1}{2}
 590 \begin{dwflisting}
 591 \begin{alltt}
 592
 593     \DWTAGcompileunit
 594         \DWATproducer [\DWFORMstrx]: (slot 15) (producer string)
 595         \DWATlanguage: \DWLANGCplusplus
 596         \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
 597         \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
 598         \DWATdwoid [\DWFORMdataeight]: 0x44e413b8a2d1b8f
 599 1$:   \DWTAGclasstype
 600           \DWATname [\DWFORMstrx]: (slot 12) "Point"
 601           \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
 602           \DWATdeclaration: true
 603 2$:     \DWTAGsubprogram
 604           \DWATexternal: true
 605           \DWATname [\DWFORMstrx]: (slot 12) "Point"
 606           \DWATdeclfile: 1
 607           \DWATdeclline: 5
 608           \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff"
 609           \DWATaccessibility: \DWACCESSpublic
 610           \DWATdeclaration: true
 611         ...
 612 3$:   \DWTAGclasstype
 613           \DWATname [\DWFORMstring]: "Box"
 614           \DWATsignature [\DWFORMrefsigeight]: 0xe97a3917c5a6529b
 615           \DWATdeclaration: true
 616         ...
 617 4$:     \DWTAGsubprogram
 618             \DWATexternal: true
 619             \DWATname [\DWFORMstrx]: (slot 0) "contains"
 620             \DWATdeclfile: 1
 621             \DWATdeclline: 28
 622             \DWATlinkagename [\DWFORMstrx]: (slot 8) "_ZNK3Box8containsERK5Point"
 623             \DWATtype: (reference to 7$)
 624             \DWATaccessibility: \DWACCESSpublic
 625             \DWATdeclaration: true
 626         ...
 627 \end{alltt}
 628 \end{dwflisting}
 629 \caption{Split object example: \texttt{demo1.dwo} excerpts}
 630 \label{fig:splitobjectexampledemo1dwodwarfexcerpts}
 631 \end{figure}
 632
 633 \begin{figure}
 634 \figurepart{2}{2}
 635 \begin{dwflisting}
 636 \begin{alltt}
 637
 638 5$:   \DWTAGsubprogram
 639           \DWATspecification: (reference to 4$)
 640           \DWATdeclfile: 2
 641           \DWATdeclline: 3
 642           \DWATlowpc [\DWFORMaddrx]: (slot 0)
 643           \DWAThighpc [\DWFORMdataeight]: 0xbb
 644           \DWATframebase: \DWOPcallframecfa
 645           \DWATobjectpointer: (reference to 6$)
 646 6$:     \DWTAGformalparameter
 647             \DWATname [\DWFORMstrx]: (slot 13): "this"
 648             \DWATtype: (reference to 8$)
 649             \DWATartificial: true
 650             \DWATlocation: \DWOPfbreg(-24)
 651         \DWTAGformalparameter
 652             \DWATname [\DWFORMstring]: "p"
 653             \DWATdeclfile: 2
 654             \DWATdeclline: 3
 655             \DWATtype: (reference to 11$)
 656             \DWATlocation: \DWOPfbreg(-32)
 657       ...
 658 7$:   \DWTAGbasetype
 659           \DWATbytesize: 1
 660           \DWATencoding: \DWATEboolean
 661           \DWATname [\DWFORMstrx]: (slot 5) "bool"
 662       ...
 663 8$:   \DWTAGconsttype
 664           \DWATtype: (reference to 9$)
 665 9$:   \DWTAGpointertype
 666           \DWATbytesize: 8
 667           \DWATtype: (reference to 10$)
 668 10$:  \DWTAGconsttype
 669           \DWATtype: (reference to 3$)
 670       ...
 671 11$:  \DWTAGconsttype
 672           \DWATtype: (reference to 12$)
 673 12$:  \DWTAGreferencetype
 674           \DWATbytesize: 8
 675           \DWATtype: (reference to 13$)
 676 13$:  \DWTAGconsttype
 677           \DWATtype: (reference to 1$)
 678       ...
 679 \end{alltt}
 680 \end{dwflisting}
 681 \begin{center}
 682 \vspace{3mm}
 683 Figure~\ref{fig:splitobjectexampledemo1dwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
 684 \end{center}
 685 \end{figure}
 686
 687 In the defining declaration for \texttt{Box::contains} at 5\$, the
 688 \DWATlowpc{} attribute is represented with \DWFORMaddrx,
 689 referring to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
 690 That slot contains the relocated address of the beginning of the
 691 function.
 692
 693 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
 694 section, and looks like a normal type unit in a non-split object,
 695 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
 696 attribute that refers to a specialized \dotdebuglinedwo{}
 697 \addtoindexx{type unit!specialized \texttt{.debug\_line.dwo} section in}
 698 \addtoindexx{specialized \texttt{.debug\_line.dwo} section}
 699 section. This
 700 section contains a normal line number
 701 program header with a list of include directories and filenames,
 702 but no line number program. This section is used only as a
 703 reference for filenames needed for \DWATdeclfile{} attributes
 704 within the type unit.
 705
 706 The \dotdebugstroffsetsdwo{} section contains an entry for each
 707 unique string in the string table. In the \texttt{demo1.dwo} example,
 708 these string table slots have been assigned as shown in
 709 Figure \refersec{fig:splitobjectexamplestringtableslots}.
 710
 711 \begin{figure}[H]
 712 \begin{center}
 713 \small
 714 %\footnotesize
 715 \begin{tabular}{cl|cl}
 716     Slot & String & Slot & String \\
 717     \hline
 718     0  &   contains                         &    10 &   \_ZNK3Box1rEv \\
 719     1  &   \_ZNK5Point1xEv                  &    11 &   \_ZN3BoxC4E5PointS0\_ \\
 720     2  &   \_ZNK3Box1lEv                    &    12 &   Point\\
 721     3  &   \_ZNK3Box1bEv                    &    13 &   this\\
 722     4  &   \textit{(compilation directory)} &    14 &   float \\
 723     5  &   bool                             &    15 &   \textit{(producer string)} \\
 724     6  &   \_ZN3BoxC4Effff                  &    16 &   \_ZN5PointC4Eff \\
 725     7  &   demo1.cc                         &    17 &   \_ZNK3Box1tEv \\
 726     8  &   \_ZNK3Box8containsERK5Point      & \\
 727     9  &   \_ZNK5Point1yEv                  & \\
 728 \end{tabular}
 729 \end{center}
 730 \caption{Split object example: String table slots}
 731 \label{fig:splitobjectexamplestringtableslots}
 732 \end{figure}
 733
 734 Each entry in the table is the offset of the string, which is
 735 contained in the \dotdebugstrdwo{} section.
 736
 737 In a split DWARF object file, all references to
 738 strings go through this table (there are no
 739 other offsets to \dotdebugstrdwo{} in a split
 740 DWARF object file). That is, there
 741 is no use of \DWFORMstrp{} in a split DWARF object file.
 742
 743 The offsets in these slots have no associated relocations,
 744 because they are not part of a relocatable object file.
 745
 746 When combined into a DWARF package file, however, each
 747 slot must be adjusted to refer to the appropriate offset
 748 within the merged string table (\dotdebugstrdwo{}).
 749 The tool that builds the DWARF package file must understand
 750 the structure of the \dotdebugstroffsetsdwo{} section in
 751 order to apply the necessary adjustments.
 752 (See Section \refersec{app:dwarfpackagefileexample}
 753 for an example of a DWARF package file.)
 754
 755 \needlines{4}
 756 The \dotdebuglocdwo{} section contains the location lists referenced
 757 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
 758 section has a similar format to the \dotdebugloc{} section in a
 759 non-split object, but it has some small differences as explained
 760 in Section \refersec{datarep:locationlistentriesinsplitobjects}.
 761 In \texttt{demo2.dwo} as shown in
 762 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts},
 763 the debugging information for \texttt{Line::clip} describes a local
 764 variable \texttt{slope} whose location varies based on the PC.
 765 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
 766 presents some excerpts from the \dotdebuginfodwo{} section for
 767 \texttt{demo2.dwo}.
 768
 769 \begin{figure}[b]
 770 \figurepart{1}{2}
 771 \begin{dwflisting}
 772 \begin{alltt}
 773
 774 1$: \DWTAGclasstype
 775         \DWATname [\DWFORMstrx]: (slot 20) "Line"
 776         \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
 777         \DWATdeclaration: true
 778     ...
 779 2$:   \DWTAGsubprogram
 780           \DWATexternal: true
 781           \DWATname [\DWFORMstrx]: (slot 19) "clip"
 782           \DWATdeclfile: 2
 783           \DWATdeclline: 16
 784           \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
 785           \DWATtype: (reference to DIE for bool)
 786           \DWATaccessibility: \DWACCESSpublic
 787           \DWATdeclaration: true
 788       ...
 789 \end{alltt}
 790 \end{dwflisting}
 791 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
 792 \label{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}
 793 \end{figure}
 794
 795 \begin{figure}
 796 \figurepart{2}{2}
 797 \begin{dwflisting}
 798 \begin{alltt}
 799
 800 3$:   \DWTAGsubprogram
 801           \DWATspecification: (reference to 2$)
 802           \DWATdeclfile: 1
 803           \DWATdeclline: 3
 804           \DWATlowpc [\DWFORMaddrx]: (slot 32)
 805           \DWAThighpc [\DWFORMdataeight]: 0x1ec
 806           \DWATframebase: \DWOPcallframecfa
 807           \DWATobjectpointer: (reference to 4$)
 808 4$:     \DWTAGformalparameter
 809             \DWATname: (indexed string: 0x11): this
 810             \DWATtype: (reference to DIE for type const Point* const)
 811             \DWATartificial: 1
 812             \DWATlocation: 0x0 (location list)
 813 5$:     \DWTAGformalparameter
 814             \DWATname: b
 815             \DWATdeclfile: 1
 816             \DWATdeclline: 3
 817             \DWATtype: (reference to DIE for type const Box& const)
 818             \DWATlocation [\DWFORMsecoffset]: 0x2a
 819 6$:     \DWTAGlexicalblock
 820             \DWATlowpc [\DWFORMaddrx]: (slot 17)
 821             \DWAThighpc: 0x1d5
 822 7$:       \DWTAGvariable
 823               \DWATname [\DWFORMstrx]: (slot 28): "slope"
 824               \DWATdeclfile: 1
 825               \DWATdeclline: 5
 826               \DWATtype: (reference to DIE for type float)
 827               \DWATlocation [\DWFORMsecoffset]: 0x49
 828
 829 \end{alltt}
 830 \end{dwflisting}
 831 \begin{center}
 832 \vspace{3mm}
 833 Figure~\ref{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
 834 \end{center}
 835 \end{figure}
 836
 837 In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts},
 838 The \DWTAGformalparameter{} entries at 4\$ and 5\$ refer to the
 839 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
 840 \DWTAGvariable{} entry for \texttt{slope} at 7\$ refers to the location
 841 list at offset \texttt{0x49}.
 842 Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
 843 shows a representation of the
 844 location lists at those offsets in the \dotdebuglocdwo{} section.
 845
 846 \begin{figure}
 847 \begin{dwflisting}
 848 \begin{tabular}{rlrrl}
 849 \texttt{offset} & entry type & start & length & expression \\
 850 \hline \\
 851 0x00 & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfive~(rdi) \\
 852 0x09 & \DWLLEstartlengthentry & [11] & 0x01b9 & \DWOPregthree~(rbx) \\
 853 0x12 & \DWLLEstartlengthentry & [29] & 0x0003 & \DWOPbregtwelve~(r12):\\
 854 &&&& -8; \DWOPstackvalue \\
 855 0x1d & \DWLLEstartlengthentry & [31] & 0x0001 & \DWOPentryvalue: \\
 856 &&&& (\DWOPregfive~(rdi)); \\
 857 &&&& \DWOPstackvalue \\
 858 0x29 & \DWLLEendoflistentry &&& \\
 859 \\   & \hhline{-} &&& \\
 860 0x2a & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfour~(rsi)) \\
 861 0x33 & \DWLLEstartlengthentry & [11] & 0x01ba & \DWOPregsix~(rbp)) \\
 862 0x3c & \DWLLEstartlengthentry & [30] & 0x0003 & \DWOPentryvalue: \\
 863 &&&& (\DWOPregfour~(rsi)); \\
 864 &&&& \DWOPstackvalue \\
 865 0x48 & \DWLLEendoflistentry &&& \\
 866 \\   & \hhline{-} &&& \\
 867 0x49 & \DWLLEstartlengthentry & [10] & 0x0004 & \DWOPregeighteen~(xmm1) \\
 868 0x52 & \DWLLEstartlengthentry & [11] & 0x01bd & \DWOPfbreg: -36 \\
 869 0x5c & \DWLLEendoflistentry &&& \\
 870 &&&& \\
 871 \end{tabular}
 872 \end{dwflisting}
 873 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
 874 \label{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
 875 \end{figure}
 876
 877 In each \DWLLEstartlengthentry{}, the start field is the index
 878 of a slot in the \dotdebugaddr{} section, relative to the base
 879 offset defined by the compilations unit's \DWATaddrbase{}
 880 attribute. The \dotdebugaddr{} slots referenced by these entries give
 881 the relocated address of a label within the function where the
 882 address range begins. The length field gives the length of the
 883 address range.
 884
 885 \clearpage
 886 \section{DWARF Package File Example}
 887 \label{app:dwarfpackagefileexample}
 888 \addtoindexx{DWARF duplicate elimination!examples}
 889 [TBD]