dwarf5/latexdoc/splitobjects.tex

   1 \chapter[Split DWARF Objects (Informative)]{Split DWARF Objects (Informative)}
   2 \label{app:splitdwarfobjectsinformative}
   3
   4 With the traditional DWARF format, debug information is designed
   5 with the expectation that it will be processed by the linker to
   6 produce an output binary with complete debug information, and
   7 with fully-resolved references to locations within the
   8 application. For very large applications, however, this approach
   9 can result in excessively large link times and excessively large
  10 output files.
  11
  12 Several vendors have independently developed
  13 proprietary approaches that allow the debug information to remain
  14 in the relocatable object files, so that the linker does not have
  15 to process the debug information or copy it to the output file.
  16 These approaches have all required that additional information be
  17 made available to the debug information consumer, and that the
  18 consumer perform some minimal amount of relocation in order to
  19 interpret the debug info correctly. The additional information
  20 required, in the form of load maps or symbol tables, and the
  21 details of the relocation are not covered by the DWARF
  22 specification, and vary with each vendor's implementation.
  23
  24 These limitations are removed by the design described here.
  25
  26 \section{Overview}
  27 \label{app:splitoverview}
  28 \DWARFVersionV{} introduces an optional set of debugging sections
  29 that allow the compiler to partition the debugging information
  30 into a set of (small) sections that require link-time relocation
  31 and a set of (large) sections that do not. The sections that
  32 require relocation are written to the relocatable object file as
  33 usual, and are linked into the final executable. The sections
  34 that do not require relocation, however, can be written to the
  35 relocatable object (.o) file but ignored by the linker, or they
  36 can be written to a separate DWARF object (dwo{}) file.
  37
  38 \needlines{4}
  39 The optional set of debugging sections includes the following:
  40 \begin{itemize}
  41 \item
  42 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
  43 \DWTAGtypeunit{} DIEs and
  44 their descendants. This is the bulk of the debugging
  45 information for the compilation unit that is normally found
  46 in the \dotdebuginfo{} section.
  47 \item
  48 \dotdebugabbrevdwo{} - Contains the abbreviations tables used by
  49 the \dotdebuginfodwo{} sections.
  50 \item
  51 \dotdebuglocdwo{} - Contains the location lists referenced by
  52 the debugging information entries in the \dotdebuginfodwo{}
  53 section. This contains the location lists normally found in
  54 the \dotdebugloc{} section,
  55 with a slightly modified format to eliminate the need for
  56 relocations.
  57 \item
  58 \dotdebugstrdwo{} - Contains the string table for all indirect
  59 strings referenced by the debugging information in the
  60 \dotdebuginfodwo{} sections.
  61 \item
  62 \dotdebugstroffsetsdwo{} - Contains the string offsets table
  63 for the strings in the \dotdebugstrdwo{}{} section.
  64 \item
  65 \dotdebugmacrodwo{} - Contains macro definition information,
  66 normally found in the \dotdebugmacro{} section.
  67 \item
  68 \dotdebuglinedwo{} - Contains skeleton line tables for the type
  69 units in the \dotdebuginfodwo{} section. These line tables
  70 contain only the directory and files lists needed to
  71 interpret \DWATdeclfile{} attributes in the debugging
  72 information entries. Actual line number tables remain in the
  73 \dotdebugline{} section, and remain in the relocatable object
  74 (.o) files.
  75 \end{itemize}
  76
  77 In order for the consumer to locate and process the debug
  78 information, the compiler must produce a small amount of debug
  79 information that passes through the linker into the output
  80 binary. A skeleton \dotdebuginfo{} section for each compilation unit
  81 contains a reference to the corresponding ".o" or ".dwo"
  82 file, and the \dotdebugline{} section (which is typically small
  83 compared to the \dotdebuginfo{} sections) is
  84 linked into the output binary, as is the new \dotdebugaddr{}
  85 section.
  86
  87 \needlines{6}
  88 The debug sections that continue to be linked into the
  89 output binary include the following:
  90 \begin{itemize}
  91 \item
  92 \dotdebugabbrev{} - Contains the abbreviation codes used by the
  93 skeleton \dotdebuginfo{} section.
  94 \item
  95 \dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
  96 but no children.
  97 \item
  98 \dotdebugstr{} - Contains any strings referenced by the skeleton
  99 \dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
 100 \item
 101 \dotdebugstroffsets{} - Contains the string offsets table for
 102 the strings in the \dotdebugstr{} section.
 103 \item
 104 \dotdebugaddr{} - Contains references to loadable sections,
 105 indexed by attributes of form \DWFORMaddrx{} or location
 106 expression \DWOPaddrx{} opcodes.
 107 \item
 108 \dotdebugline{} - Contains the line number tables, unaffected by
 109 this design. (These could be moved to the .dwo file, but in
 110 order to do so, each \DWLNEsetaddress{} opcode would need to
 111 be replaced by a new opcode that referenced an entry in the
 112 \dotdebugaddr{} section. Furthermore, leaving this section in the
 113 .o file allows many debug info consumers to remain unaware of
 114 .dwo files.)
 115 \item
 116 \dotdebugframe{} - Contains the frame tables, unaffected by this
 117 design.
 118 \item
 119 \dotdebugranges{} - Contains the range lists, unaffected by this
 120 design.
 121 \item
 122 \dotdebugpubnames{} - Contains the public names for use in
 123 building an index section. This section has the same
 124 format and use as always. The section header refers to a
 125 compilation unit offset, which is the offset of the
 126 skeleton compilation unit in the \dotdebuginfo{} section.
 127 \item
 128 \dotdebugpubtypes{} - Contains the public types for use in
 129 building an index section. This section has the same
 130 format and use as always. The section header refers to a
 131 compilation unit offset, which is the offset of the
 132 skeleton compilation unit in the \dotdebuginfo{} section.
 133 \item
 134 \dotdebugaranges{} - Contains the accelerated range lookup table
 135 for the compilation unit, unaffected by this design.
 136 \end{itemize}
 137
 138 \needlines{6}
 139 The skeleton \DWTAGcompileunit{} DIE has the following attributes:
 140 \autocols[0pt]{c}{3}{l}{
 141 \DWATaddrbase{},
 142 \DWATcompdir{},
 143 \DWATdwoname{},
 144 \DWATdwoid{},
 145 \DWAThighpc{} \dag,
 146 \DWATlowpc{} \dag,
 147 \DWATranges{} \dag,
 148 \DWATrangesbase{},
 149 \DWATstmtlist{},
 150 \DWATstroffsetsbase{}
 151 }
 152 \dag{} If \DWATranges{} is present, \DWATlowpc{} and \DWAThighpc{} are
 153 not used, and vice versa.
 154
 155 All other attributes of the compilation unit DIE are moved to
 156 the full DIE in the \dotdebuginfodwo{} section.
 157
 158 Because of other improvements in \DWARFVersionV, most of the
 159 relocations that would normally be found in the \dotdebuginfodwo{}
 160 sections are moved to the \dotdebugaddr{} and
 161 \dotdebugstroffsetsdwo{} sections. Those in the
 162 \dotdebugstroffsetsdwo{} sections are simply omitted because the
 163 DWARF information in those sections is not combined at link
 164 time, so no relocation is necessary. Similarly,
 165 many of the remaining relocations referring to range lists are
 166 eliminated.
 167
 168 The relocations that remain fall into the following categories:
 169 \begin{itemize}
 170 \item
 171 References from compilation unit and type unit headers to the
 172 \dotdebugabbrevdwo{} section. Because the new sections are not
 173 combined at link time, these references need no relocations.
 174 \item
 175 References from \DWTAGcompileunit{} DIEs to the
 176 \dotdebuglinedwo{} section, via \DWATstmtlist{}. This attribute
 177 remains in the skeleton \dotdebuginfo{} section, so no
 178 relocation in the \dotdebuginfodwo{} section is necessary.
 179 \item
 180 References from \DWTAGtypeunit{} DIEs to the skeleton
 181 \dotdebuglinedwo{} section, via \DWATstmtlist{}. Because the new
 182 sections are not combined at link time, these references need
 183 no relocations.
 184 \item
 185 References from \DWTAGcompileunit{} and \DWTAGtypeunit{} DIEs
 186 to the \dotdebugstroffsetsdwo{} section, via
 187 \DWATstroffsetsbase{}. Because the new sections are not
 188 combined at link time, the \DWATstroffsetsbase{} attribute
 189 is not required in a \dotdebuginfodwo{}
 190 section.
 191 \item
 192 References from \DWTAGcompileunit{} DIEs to the \dotdebugaddr{}
 193 section, via \DWATaddrbase{}. This attribute remains in
 194 the skeleton \dotdebuginfo{} section, so no relocation in the
 195 \dotdebuginfodwo{} section is necessary.
 196 \needlines{4}
 197 \item
 198 References from \DWTAGcompileunit{} DIEs to the \dotdebugranges{}
 199 section, via \DWATrangesbase{}. This attribute remains in
 200 the skeleton \dotdebuginfo{} section, so no relocation in the
 201 \dotdebuginfodwo{} section is necessary.
 202 \item
 203 References from the \dotdebuglocdwo{} section to machine addresses
 204 via a location list entry or a base address selection entry.
 205 With a minor change to the location list entry format,
 206 described below, these relocations are also eliminated.
 207 \end{itemize}
 208
 209 Each location list entry contains beginning and ending address
 210 offsets, which normally may be relocated addresses. In the
 211 \dotdebuglocdwo{} section, these offsets are replaced by indices
 212 into the \dotdebugaddr{} section. Each location list entry begins
 213 with a single byte identifying the entry type:
 214 \begin{itemize}
 215 \item
 216 \DWLLEendoflistentry{} (0) indicates an end-of-list entry,
 217 \item
 218 \DWLLEbaseaddressselectionentry{} (1) indicates a base address
 219 selection entry,
 220 \item
 221 \DWLLEstartendentry{} (2) indicates a normal
 222 location list entry providing start and end addresses,
 223 \item
 224 \DWLLEstartlengthentry{} (3) indicates a normal location list
 225 entry providing a start address and a length, and
 226 \item
 227 \DWLLEoffsetpairentry{} (4) indicates a normal location list
 228 entry providing start and end offsets relative to the base
 229 address.
 230 \end{itemize}
 231 An end-of-list entry has no further data. A base address
 232 selection entry contains a single unsigned LEB128 number
 233 following the entry type byte, which is an index into the
 234 \dotdebugaddr{} section that selects the new base address for
 235 subsequent location list entries. A start/end entry contains two
 236 unsigned LEB128 numbers following the entry type byte, which are
 237 indices into the \dotdebugaddr{} section that select the beginning
 238 and ending addresses. A start/length entry contains one unsigned
 239 LEB128 number and a 4-byte unsigned value (as would be
 240 represented by the form code \DWFORMdatafour). The first number
 241 is an index into the \dotdebugaddr{} section that selects the
 242 beginning offset, and the second number is the length of the
 243 range. Addresses fetched from the \dotdebugaddr{} section are not
 244 relative to the base address. An offset pair entry contains two
 245 4-byte unsigned values (as would be represented by the form code
 246 \DWFORMdatafour){}, treated as the beginning and ending offsets,
 247 respectively, relative to the base address. As in the \dotdebugloc{}
 248 section, the base address is obtained either from the nearest
 249 preceding base address selection entry, or, if there is no such
 250 entry, from the compilation unit base address (as defined in
 251 Section 3.1.1). For the latter three types (start/end,
 252 start/length, and offset pair), the two operand values are
 253 followed by a location description as in a normal location list
 254 entry in the \dotdebugloc{} section.
 255
 256 This design depends on having an index of debugging information
 257 available to the consumer. For name lookups, the consumer can use
 258 the \dotdebugpubnames{} and \dotdebugpubtypes{} sections (or an index
 259 built at link time based on the information in those sections),
 260 which will lead to a skeleton compilation unit. The
 261 \DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
 262 compilation unit can then be used to locate the corresponding
 263 DWARF object file for the compilation unit. Similarly, for an
 264 address lookup, the consumer can use the \dotdebugaranges{} table,
 265 which will also lead to a skeleton compilation unit. For a file
 266 and line number lookup, the skeleton compilation units can be
 267 used to locate the line number tables.
 268
 269 \section{Split DWARF Object Examples}
 270 \label{app:splitdwarfobjectexamples}
 271
 272 TBD