dwarf5/latexdoc/datarepresentation.tex

   1 \chapter{Data Representation}
   2 \label{datarep:datarepresentation}
   3
   4 This section describes the binary representation of the
   5 debugging information entry itself, of the attribute types
   6 and of other fundamental elements described above.
   7
   8 \section{Vendor Extensibility}
   9 \label{datarep:vendorextensibility}
  10 \addtoindexx{vendor extensibility}
  11 \addtoindexx{vendor specific extensions|see{vendor extensibility}}
  12
  13 To
  14 \addtoindexx{extensibility|see{vendor extensibility}}
  15 reserve a portion of the DWARF name space and ranges of
  16 enumeration values for use for vendor specific extensions,
  17 special labels are reserved for tag names, attribute names,
  18 base type encodings, location operations, language names,
  19 calling conventions and call frame instructions.
  20
  21 The labels denoting the beginning and end of the
  22 \hypertarget{chap:DWXXXlohiuser}{reserved value range}
  23 for vendor specific extensions consist of the
  24 appropriate prefix
  25 (\DWATlouserMARK{}\DWAThiuserMARK{}DW\_AT,
  26 \DWATElouserMARK{}\DWATEhiuserMARK{}DW\_ATE,
  27 \DWCClouserMARK{}\DWCChiuserMARK{}DW\_CC,
  28 \DWCFAlouserMARK{}\DWCFAhiuserMARK{}DW\_CFA,
  29 \DWENDlouserMARK{}\DWENDhiuserMARK{}DW\_END,
  30 \DWIDXlouserMARK{}\DWIDXhiuserMARK{}DW\_IDX,
  31 \DWLANGlouserMARK{}\DWLANGhiuserMARK{}DW\_LANG,
  32 \DWLNCTlouserMARK{}\DWLNCThiuserMARK{}DW\_LNCT,
  33 \DWLNElouserMARK{}\DWLNEhiuserMARK{}DW\_LNE,
  34 \DWMACROlouserMARK{}\DWMACROhiuserMARK{}DW\_MACRO,
  35 \bb
  36 \DWOPlouserMARK{}\DWOPhiuserMARK{}DW\_OP,
  37 \DWTAGlouserMARK{}\DWTAGhiuserMARK{}DW\_TAG,
  38 \DWUTlouserMARK{}\DWUThiuserMARK{}DW\_UT)
  39 \eb
  40 followed by \_lo\_user or \_hi\_user.
  41 Values in the  range between \textit{prefix}\_lo\_user
  42 and \textit{prefix}\_hi\_user inclusive,
  43 are reserved for vendor specific extensions. Vendors may
  44 use values in this range without conflicting with current or
  45 future system\dash defined values. All other values are reserved
  46 for use by the system.
  47
  48 \textit{For example, for debugging information entry
  49 tags, the special labels are \DWTAGlouserNAME{} and \DWTAGhiuserNAME.}
  50
  51 \textit{There may also be codes for vendor specific extensions
  52 between the number of standard line number opcodes and
  53 the first special line number opcode. However, since the
  54 number of standard opcodes varies with the DWARF version,
  55 the range for extensions is also version dependent. Thus,
  56 \DWLNSlouserTARG{} and
  57 \DWLNShiuserTARG{} symbols are not defined.}
  58
  59 Vendor defined tags, attributes, base type encodings, location
  60 atoms, language names, line number actions, calling conventions
  61 and call frame instructions, conventionally use the form
  62 \text{prefix\_vendor\_id\_name}, where
  63 \textit{vendor\_id}\addtoindexx{vendor id} is some identifying
  64 character sequence chosen so as to avoid conflicts with
  65 other vendors.
  66
  67 To ensure that extensions added by one vendor may be safely
  68 ignored by consumers that do not understand those extensions,
  69 the following rules must be followed:
  70 \begin{enumerate}[1. ]
  71
  72 \item New attributes are added in such a way that a
  73 debugger may recognize the format of a new attribute value
  74 without knowing the content of that attribute value.
  75
  76 \item The semantics of any new attributes do not alter
  77 the semantics of previously existing attributes.
  78
  79 \item The semantics of any new tags do not conflict with
  80 the semantics of previously existing tags.
  81
  82 \item New forms of attribute value are not added.
  83
  84 \end{enumerate}
  85
  86
  87 \section{Reserved Values}
  88 \label{datarep:reservedvalues}
  89 \subsection{Error Values}
  90 \label{datarep:errorvalues}
  91 \addtoindexx{reserved values!error}
  92
  93 As
  94 \addtoindexx{error value}
  95 a convenience for consumers of DWARF information, the value
  96 0 is reserved in the encodings for attribute names, attribute
  97 forms, base type encodings, location operations, languages,
  98 line number program opcodes, macro information entries and tag
  99 names to represent an error condition or unknown value. DWARF
 100 does not specify names for these reserved values, because they
 101 do not represent valid encodings for the given type and do
 102 not appear in DWARF debugging information.
 103
 104
 105 \subsection{Initial Length Values}
 106 \label{datarep:initiallengthvalues}
 107 \addtoindexx{reserved values!initial length}
 108
 109 An \livetarg{datarep:initiallengthvalues}{initial length} field
 110 \addtoindexx{initial length field|see{initial length}}
 111 is one of the fields that occur at the beginning
 112 of those DWARF sections that have a header
 113 (\dotdebugaranges{},
 114 \dotdebuginfo{},
 115 \dotdebugline{},
 116 \dotdebugloclists{},
 117 \dotdebugnames{} and
 118 \dotdebugrnglists)
 119 or the length field
 120 that occurs at the beginning of the CIE and FDE structures
 121 in the \dotdebugframe{} section.
 122
 123 \needlines{4}
 124 In an \addtoindex{initial length} field, the values \wfffffffzero through
 125 \wffffffff are reserved by DWARF to indicate some form of
 126 extension relative to \DWARFVersionII; such values must not
 127 be interpreted as a length field. The use of one such value,
 128 \xffffffff, is defined in
 129 Section \refersec{datarep:32bitand64bitdwarfformats});
 130 the use of
 131 the other values is reserved for possible future extensions.
 132
 133
 134 \section{Relocatable, Split, Executable, Shared, Package and Supplementary Object Files}
 135 \label{datarep:executableobjectsandsharedobjects}
 136
 137 \subsection{Relocatable Object Files}
 138 \label{datarep:relocatableobjectfiles}
 139 A DWARF producer (for example, a compiler) typically generates its
 140 debugging information as part of a relocatable object file.
 141 Relocatable object files are then combined by a linker to form an
 142 executable file. During the linking process, the linker resolves
 143 (binds) symbolic references between the various object files, and
 144 relocates the contents of each object file into a combined virtual
 145 address space.
 146
 147 The DWARF debugging information is placed in several sections (see
 148 Appendix \refersec{app:debugsectionrelationshipsinformative}), and
 149 requires an object file format capable of
 150 representing these separate sections. There are symbolic references
 151 between these sections, and also between the debugging information
 152 sections and the other sections that contain the text and data of the
 153 program itself. Many of these references require relocation, and the
 154 producer must emit the relocation information appropriate to the
 155 object file format and the target processor architecture. These
 156 references include the following:
 157
 158 \begin{itemize}
 159 \item The compilation unit header (see Section
 160 \refersec{datarep:unitheaders}) in the \dotdebuginfo{}
 161 section contains a reference to the \dotdebugabbrev{} table. This
 162 reference requires a relocation so that after linking, it refers to
 163 that contribution to the combined \dotdebugabbrev{} section in the
 164 executable file.
 165
 166 \item Debugging information entries may have attributes with the form
 167 \DWFORMaddr{} (see Section \refersec{datarep:attributeencodings}).
 168 These attributes represent locations
 169 within the virtual address space of the program, and require
 170 relocation.
 171
 172 \item A DWARF expression may contain a \DWOPaddr{} (see Section
 173 \refersec{chap:literalencodings}) which contains a location within
 174 the virtual address space of the program, and require relocation.
 175
 176 \needlines{4}
 177 \item Debugging information entries may have attributes with the form
 178 \DWFORMsecoffset{} (see Section \refersec{datarep:attributeencodings}).
 179 These attributes refer to
 180 debugging information in other debugging information sections within
 181 the object file, and must be relocated during the linking process.
 182
 183 \item Debugging information entries may have attributes with the form
 184 \DWFORMrefaddr{} (see Section \refersec{datarep:attributeencodings}).
 185 These attributes refer to
 186 debugging information entries that may be outside the current
 187 compilation unit. These values require both symbolic binding and
 188 relocation.
 189
 190 \item Debugging information entries may have attributes with the form
 191 \DWFORMstrp{} (see Section \refersec{datarep:attributeencodings}).
 192 These attributes refer to strings in
 193 the \dotdebugstr{} section. These values require relocation.
 194
 195 \item Entries in the \dotdebugaddr{} and \dotdebugaranges{}
 196 sections may contain references to locations within the virtual address
 197 space of the program, and thus require relocation.
 198
 199 \item Entries in the \dotdebugloclists{} and \dotdebugrnglists{} sections may
 200 contain references to locations within the virtual address space of the
 201 program depending on whether certain kinds of location or range
 202 list entries are used, and thus require relocation.
 203
 204 \item In the \dotdebugline{} section, the operand of the \DWLNEsetaddress{}
 205 opcode is a reference to a location within the virtual address space
 206 of the program, and requires relocation.
 207
 208 \item The \dotdebugstroffsets{} section contains a list of string offsets,
 209 each of which is an offset of a string in the \dotdebugstr{} section. Each
 210 of these offsets requires relocation. Depending on the implementation,
 211 these relocations may be implicit (that is, the producer may not need to
 212 emit any explicit relocation information for these offsets).
 213
 214 \item The \HFNdebuginfooffset{} field in the \dotdebugaranges{} header and
 215 the list of compilation units following the \dotdebugnames{} header contain
 216 references to the \dotdebuginfo{} section.  These references require relocation
 217 so that after linking they refer to the correct contribution in the combined
 218 \dotdebuginfo{} section in the executable file.
 219
 220 \item Frame descriptor entries in the \dotdebugframe{} section
 221 (see Section \refersec{chap:structureofcallframeinformation}) contain an
 222 \HFNinitiallocation{} field value within the virtual address
 223 space of the program and require relocation.
 224
 225 \end{itemize}
 226
 227 \needlines{4}
 228 \textit{Note that operands of classes
 229 \CLASSconstant{} and
 230 \CLASSflag{} do not require relocation. Attribute operands that use
 231 forms \DWFORMstring{},
 232 \DWFORMrefone, \DWFORMreftwo, \DWFORMreffour, \DWFORMrefeight, or
 233 \DWFORMrefudata{} also do not need relocation.}
 234
 235 \subsection{Split DWARF Object Files}
 236 \label{datarep:splitdwarfobjectfiles}
 237 \addtoindexx{split DWARF object file}
 238 A DWARF producer may partition the debugging
 239 information such that the majority of the debugging
 240 information can remain in individual object files without
 241 being processed by the linker.
 242
 243 \textit{This reduces link time by reducing the amount of information
 244 the linker must process.}
 245
 246 \needlines{6}
 247 \subsubsection{First Partition (with Skeleton Unit)}
 248 The first partition contains
 249 debugging information that must still be processed by the linker,
 250 and includes the following:
 251 \begin{itemize}
 252 \item
 253 The line number tables, frame tables, and
 254 accelerated access tables, in the usual sections:
 255 \dotdebugline, \dotdebuglinestr,
 256 \dotdebugframe, \dotdebugnames{} and \dotdebugaranges,
 257 respectively.
 258 \needlines{4}
 259 \item
 260 An address table, in the \dotdebugaddr{} section. This table
 261 contains all addresses and constants that require
 262 link-time relocation, and items in the table can be
 263 referenced indirectly from the debugging information via
 264 the \DWFORMaddrx{} form,
 265 by the \DWOPaddrx{} and \DWOPconstx{} operators, and
 266 by certain of the \texttt{DW\_LLE\_*} location list
 267 and \texttt{DW\_RLE\_*} range list entries.
 268 \item
 269 A skeleton compilation unit, as described in Section
 270 \refersec{chap:skeletoncompilationunitentries},
 271 in the \dotdebuginfo{} section.
 272 \item
 273 An abbreviations table for the skeleton compilation unit,
 274 in the \dotdebugabbrev{} section
 275 used by the \dotdebuginfo{} section.
 276
 277 \item
 278 A string table, in the \dotdebugstr{} section. The string
 279 table is necessary only if the skeleton compilation unit
 280 \bb
 281 uses one of the indirect string forms (\DWFORMstrp{},
 282 \DWFORMstrxXNor).
 283 \eb
 284 \item
 285 A string offsets table, in the \dotdebugstroffsets{}
 286 section for strings in the \dotdebugstr{} section.
 287 The string offsets table is necessary only if
 288 the skeleton compilation unit uses
 289 \bb
 290 one of the indexed string forms
 291 \eb
 292 (\DWFORMstrxXN).
 293 \end{itemize}
 294 The attributes contained in the skeleton compilation
 295 unit can be used by a DWARF consumer to find the
 296 DWARF object file that contains the second partition.
 297
 298 \subsubsection{Second Partition (Unlinked or in a \texttt{.dwo} File)}
 299 The second partition contains the debugging information that
 300 does not need to be processed by the linker. These sections
 301 may be left in the object files and ignored by the linker
 302 (that is, not combined and copied to the executable object file), or
 303 they may be placed by the producer in a separate DWARF object
 304 file. This partition includes the following:
 305 \begin{itemize}
 306 \item
 307 The full compilation unit, in the \dotdebuginfodwo{} section.
 308
 309 Attributes contained in the full compilation unit
 310 may refer to machine addresses indirectly using the \DWFORMaddrx{}
 311 form, which accesses the table of addresses specified by the
 312 \DWATaddrbase{} attribute in the associated skeleton unit.
 313 Location descriptions may similarly do so using the \DWOPaddrx{} and
 314 \DWOPconstx{} operations.
 315
 316 \item Separate type units, in the \dotdebuginfodwo{} section.
 317
 318 \item
 319 Abbreviations table(s) for the compilation unit and type
 320 units, in the \dotdebugabbrevdwo{} section
 321 used by the \dotdebuginfodwo{} section.
 322
 323 \item Location lists, in the
 324 \dotdebugloclistsdwo{} section.
 325
 326 \item Range lists, in the \dotdebugrnglistsdwo{} section.
 327
 328 \item
 329 A \addtoindex{specialized line number table} (for the type units),
 330 in the \dotdebuglinedwo{} section.
 331
 332 This table
 333 contains only the directory and filename lists needed to
 334 interpret \DWATdeclfile{} attributes in the debugging
 335 information entries.
 336
 337 \item Macro information, in the \dotdebugmacrodwo{} section.
 338
 339 \item A string table, in the \dotdebugstrdwo{} section.
 340
 341 \item A string offsets table, in the \dotdebugstroffsetsdwo{}
 342 section
 343 for the strings in the \dotdebugstrdwo{} section.
 344 \end{itemize}
 345
 346 Except where noted otherwise, all references in this document
 347 to a debugging information section (for example, \dotdebuginfo),
 348 apply also to the corresponding split DWARF section (for example,
 349 \dotdebuginfodwo).
 350
 351 \needlines{4}
 352 Split DWARF object files do not get linked with any other files,
 353 therefore references between sections must not make use of
 354 normal object file relocation information. As a result, symbolic
 355 references within or between sections are not possible.
 356
 357 \subsection{Executable Objects}
 358 \label{chap:executableobjects}
 359 The relocated addresses in the debugging information for an
 360 executable object are virtual addresses.
 361
 362 The sections containing the debugging information are typically
 363 not loaded as part of the memory image of the program (in ELF
 364 terminology, the sections are not "allocatable" and are not part
 365 of a loadable segment). Therefore, the debugging information
 366 sections described in this document are typically linked as if
 367 they were each to be loaded at virtual address 0, and references
 368 within the debugging information always implicitly indicate which
 369 section a particular offset refers to. (For example, a reference
 370 of form \DWFORMsecoffset{} may refer to one of several sections,
 371 depending on the class allowed by a particular attribute of a
 372 debugging information entry, as shown in
 373 Table \refersec{tab:attributeencodings}.)
 374
 375 \needlines{6}
 376 \subsection{Shared Object Files}
 377 \label{datarep:sharedobjectfiles}
 378 The relocated
 379 addresses in the debugging information for a shared object file
 380 are offsets relative to the start of the lowest region of
 381 memory loaded from that shared object file.
 382
 383 \needlines{4}
 384 \textit{This requirement makes the debugging information for
 385 shared object files position independent.  Virtual addresses in a
 386 shared object file may be calculated by adding the offset to the
 387 base address at which the object file was attached. This offset
 388 is available in the run\dash time linker\textquoteright s data structures.}
 389
 390 As with executable objects, the sections containing debugging
 391 information are typically not loaded as part of the memory image
 392 of the shared object, and are typically linked as if they were
 393 each to be loaded at virtual address 0.
 394
 395 \subsection{DWARF Package Files}
 396 \label{datarep:dwarfpackagefiles}
 397 \textit{Using \splitDWARFobjectfile{s} allows the developer to compile,
 398 link, and debug an application quickly with less link-time overhead,
 399 but a more convenient format is needed for saving the debug
 400 information for later debugging of a deployed application. A
 401 DWARF package file can be used to collect the debugging
 402 information from the object (or separate DWARF object) files
 403 produced during the compilation of an application.}
 404
 405 \textit{The package file is typically placed in the same directory as the
 406 application, and is given the same name with a \doublequote{\texttt{.dwp}}
 407 extension.\addtoindexx{\texttt{.dwp} file extension}}
 408
 409 \needlines{4}
 410 A DWARF package file is itself an object file, using the
 411 \addtoindexx{package files}
 412 \addtoindexx{DWARF package files}
 413 same object file format (including \byteorder) as the
 414 corresponding application binary. It consists only of a file
 415 header, a section table, a number of DWARF debug information
 416 sections, and two index sections.
 417
 418 \needlines{10}
 419 Each DWARF package file contains no more than one of each of the
 420 following sections, copied from a set of object or DWARF object
 421 files, and combined, section by section:
 422 \begin{alltt}
 423     \dotdebuginfodwo
 424     \dotdebugabbrevdwo
 425     \dotdebuglinedwo
 426     \dotdebugloclistsdwo
 427     \dotdebugrnglistsdwo
 428     \dotdebugstroffsetsdwo
 429     \dotdebugstrdwo
 430     \dotdebugmacrodwo
 431 \end{alltt}
 432
 433 The string table section in \dotdebugstrdwo{} contains all the
 434 strings referenced from DWARF attributes using
 435 \bb
 436 any of the forms
 437 \eb
 438 \DWFORMstrxXNor. Any attribute in a compilation unit or a type
 439 unit using this form refers to an entry in that unit's
 440 contribution to the \dotdebugstroffsetsdwo{} section, which in turn
 441 provides the offset of a string in the \dotdebugstrdwo{}
 442 section.
 443
 444 The DWARF package file also contains two index sections that
 445 provide a fast way to locate debug information by compilation
 446 unit ID for compilation units, or by type
 447 signature for type units:
 448 \begin{alltt}
 449     \dotdebugcuindex
 450     \dotdebugtuindex
 451 \end{alltt}
 452
 453 \subsubsection{The Compilation Unit (CU) Index Section}
 454 The \dotdebugcuindex{} section is a hashed lookup table that maps a
 455 compilation unit ID to a set of contributions in the
 456 various debug information sections. Each contribution is stored
 457 as an offset within its corresponding section and a size.
 458
 459 \needlines{10}
 460 Each \compunitset{} may contain contributions from the
 461 following sections:
 462 \begin{alltt}
 463     \dotdebuginfodwo{} (required)
 464     \dotdebugabbrevdwo{} (required)
 465     \dotdebuglinedwo
 466     \dotdebugloclistsdwo
 467     \dotdebugrnglistsdwo
 468     \dotdebugstroffsetsdwo
 469     \dotdebugmacrodwo
 470 \end{alltt}
 471
 472 \textit{Note that a \compunitset{} is not able to represent \dotdebugmacinfo{}
 473 information from \DWARFVersionIV{} or earlier formats.}
 474
 475 \subsubsection{The Type Unit (TU) Index Section}
 476 The \dotdebugtuindex{} section is a hashed lookup table that maps a
 477 type signature to a set of offsets in the various debug
 478 information sections. Each contribution is stored as an offset
 479 within its corresponding section and a size.
 480
 481 Each \typeunitset{} may contain contributions from the following
 482 sections:
 483 \begin{alltt}
 484     \dotdebuginfodwo{} (required)
 485     \dotdebugabbrevdwo{} (required)
 486     \dotdebuglinedwo
 487     \dotdebugstroffsetsdwo
 488 \end{alltt}
 489
 490 \subsubsection{Format of the CU and TU Index Sections}
 491 Both index sections have the same format, and serve to map an
 492 8-byte signature to a set of contributions to the debug sections.
 493 Each index section begins with a header, followed by a hash table of
 494 signatures, a parallel table of indexes, a table of offsets, and
 495 a table of sizes. The index sections are aligned at 8-byte
 496 boundaries in the DWARF package file.
 497
 498 \needlines{6}
 499 The index section header contains the following fields:
 500 \begin{enumerate}[1. ]
 501 \item \texttt{version} (\HFTuhalf) \\
 502 A version number.
 503 \addtoindexx{version number!CU index information}
 504 \addtoindexx{version number!TU index information}
 505 This number is specific to the CU and TU index information
 506 and is independent of the DWARF version number.
 507
 508 The version number is \versiondotdebugcuindex.
 509
 510 \item \textit{padding} (\HFTuhalf) \\
 511 Reserved to DWARF (must be zero).
 512
 513 \needlines{4}
 514 \item \texttt{section\_count} (\HFTuword) \\
 515 The number of entries in the table of section counts that follows.
 516 For brevity, the contents of this field is referred to as $N$ below.
 517
 518 \item \texttt{unit\_count} (\HFTuword) \\
 519 The number of compilation units or type units in the index.
 520 For brevity, the contents of this field is referred to as $U$ below.
 521
 522 \item \texttt{slot\_count} (\HFTuword) \\
 523 The number of slots in the hash table.
 524 For brevity, the contents of this field is referred to as $S$ below.
 525
 526 \end{enumerate}
 527
 528 \textit{We assume that $U$ and $S$ do not exceed $2^{32}$.}
 529
 530 The size of the hash table, $S$, must be $2^k$ such that:
 531 \hspace{0.3cm}$2^k\ \ >\ \ 3*U/2$
 532
 533 The hash table begins at offset 16 in the section, and consists
 534 of an array of $S$ 8-byte slots. Each slot contains a 64-bit
 535 signature.
 536 % (using the \byteorder{} of the application binary).
 537
 538 The parallel table of indices begins immediately after the hash table
 539 (at offset \mbox{$16 + 8 * S$} from the beginning of the section), and
 540 consists of an array of $S$ 4-byte slots,
 541 % (using the byte order of the application binary),
 542 corresponding 1-1 with slots in the hash
 543 table. Each entry in the parallel table contains a row index into
 544 the tables of offsets and sizes.
 545
 546 Unused slots in the hash table have 0 in both the hash table
 547 entry and the parallel table entry. While 0 is a valid hash
 548 value, the row index in a used slot will always be non-zero.
 549
 550 Given an 8-byte compilation unit ID or type signature $X$,
 551 an entry in the hash table is located as follows:
 552 \begin{enumerate}[1. ]
 553 \item Define $REP(X)$ to be the value of $X$ interpreted as an
 554       unsigned 64-bit integer in the target byte order.
 555 \item Calculate a primary hash $H = REP(X)\ \&\ MASK(k)$, where
 556       $MASK(k)$ is a mask with the low-order $k$ bits all set to 1.
 557 \item Calculate a secondary hash $H' = (((REP(X)>>32)\ \&\ MASK(k))\ |\ 1)$.
 558 \item If the hash table entry at index $H$ matches the signature, use
 559       that entry. If the hash table entry at index $H$ is unused (all
 560       zeroes), terminate the search: the signature is not present
 561       in the table.
 562 \item Let $H = (H + H')\ modulo\ S$. Repeat at Step 4.
 563 \end{enumerate}
 564
 565 Because $S > U$, and $H'$ and $S$ are relatively prime, the search is
 566 guaranteed to stop at an unused slot or find the match.
 567
 568 \needlines{4}
 569 The table of offsets begins immediately following the parallel
 570 table (at offset \mbox{$16 + 12 * S$} from the beginning of the section).
 571 This table consists of a single header row containing $N$ fields,
 572 each a 4-byte unsigned integer, followed by $U$ data rows, each
 573 also containing $N$ fields of 4-byte unsigned integers. The fields
 574 in the header row provide a section identifier referring to a
 575 debug section; the available section identifiers are shown in
 576 Table \referfol{tab:dwarfpackagefilesectionidentifierencodings}.
 577 Each data row corresponds to a specific CU
 578 or TU in the package file. In the data rows, each field provides
 579 an offset to the debug section whose identifier appears in the
 580 corresponding field of the header row. The data rows are indexed
 581 starting at 1.
 582
 583 \textit{Not all sections listed in the table need be included.}
 584
 585 \needlines{12}
 586 \begin{centering}
 587 \setlength{\extrarowheight}{0.1cm}
 588 \begin{longtable}{l|c|l}
 589   \caption{DWARF package file section identifier \mbox{encodings}}
 590   \label{tab:dwarfpackagefilesectionidentifierencodings}
 591   \addtoindexx{DWARF package files!section identifier encodings} \\
 592   \hline \bfseries Section identifier &\bfseries Value &\bfseries Section \\ \hline
 593 \endfirsthead
 594   \bfseries Section identifier &\bfseries Value &\bfseries Section\\ \hline
 595 \endhead
 596   \hline \emph{Continued on next page}
 597 \endfoot
 598   \hline
 599 \endlastfoot
 600 \DWSECTINFOTARG         & 1 & \dotdebuginfodwo \\
 601 \textit{Reserved}       & 2 & \\
 602 \DWSECTABBREVTARG       & 3 & \dotdebugabbrevdwo \\
 603 \DWSECTLINETARG         & 4 & \dotdebuglinedwo \\
 604 \DWSECTLOCLISTSTARG     & 5 & \dotdebugloclistsdwo \\
 605 \DWSECTSTROFFSETSTARG   & 6 & \dotdebugstroffsetsdwo \\
 606 \DWSECTMACROTARG        & 7 & \dotdebugmacrodwo \\
 607 \DWSECTRNGLISTSTARG         & 8 & \dotdebugrnglistsdwo \\
 608 \end{longtable}
 609 \end{centering}
 610
 611 The offsets provided by the CU and TU index sections are the
 612 base offsets for the contributions made by each CU or TU to the
 613 corresponding section in the package file. Each CU and TU header
 614 contains a \HFNdebugabbrevoffset{} field, used to find the abbreviations
 615 table for that CU or TU within the contribution to the
 616 \dotdebugabbrevdwo{} section for that CU or TU, and are
 617 interpreted as relative to the base offset given in the index
 618 section. Likewise, offsets into \dotdebuglinedwo{} from
 619 \DWATstmtlist{} attributes are interpreted as relative to
 620 the base offset for \dotdebuglinedwo{}, and offsets into other debug
 621 sections obtained from DWARF attributes are also
 622 interpreted as relative to the corresponding base offset.
 623
 624 The table of sizes begins immediately following the table of
 625 offsets, and provides the sizes of the contributions made by each
 626 CU or TU to the corresponding section in the package file.
 627 This table consists of U data rows, each with N fields of 4-byte
 628 unsigned integers. Each data row corresponds to the same CU or TU
 629 as the corresponding data row in the table of offsets described
 630 above. Within each data row, the N fields also correspond
 631 one-to-one with the fields in the corresponding data row of the
 632 table of offsets. Each field provides the size of the
 633 contribution made by a CU or TU to the corresponding section in
 634 the package file.
 635
 636 For an example, see Figure \refersec{fig:examplecuindexsection}.
 637
 638 \subsection{DWARF Supplementary Object Files}
 639 \label{datarep:dwarfsupplemetaryobjectfiles}
 640 \textit{A supplementary object file permits a post-link utility to analyze executable and
 641 shared object files and collect duplicate debugging information into a single file that
 642 can be referenced by each of the original files.  This is in contrast to split DWARF
 643 object files, which allow the compiler to split the debugging information between
 644 multiple files in order to reduce link time and executable size.}
 645
 646 \needlines{4}
 647 A DWARF \addtoindex{supplementary object file} is itself an object file,
 648 using the same object
 649 file format, \byteorder{}, and size as the corresponding application executables
 650 or shared libraries. It consists only of a file header, section table, and
 651 a number of DWARF debug information sections.  Both the
 652 \addtoindex{supplementary object file}
 653 and all the executable or shared object files that reference entries or strings in that
 654 file must contain a \dotdebugsup{} section that establishes the relationship.
 655
 656 The \dotdebugsup{} section contains:
 657 \begin{enumerate}[1. ]
 658 \item \texttt{version} (\HFTuhalf) \\
 659 \addttindexx{version}
 660 A 2-byte unsigned integer representing the version of the DWARF
 661 information for the compilation unit.
 662
 663 The value in this field is \versiondotdebugsup.
 664
 665 \item \texttt{is\_supplementary} (\HFTubyte) \\
 666 \addttindexx{is\_supplementary}
 667 A 1-byte unsigned integer, which contains the value 1 if it is
 668 in the \addtoindex{supplementary object file} that other executable or
 669 shared object files refer to, or 0 if it is an executable or shared object
 670 referring to a \addtoindex{supplementary object file}.
 671
 672 \needlines{4}
 673 \item \texttt{sup\_filename} (null terminated filename string) \\
 674 \addttindexx{sup\_filename}
 675 If \addttindex{is\_supplementary} is 0, this contains either an absolute
 676 filename for the \addtoindex{supplementary object file}, or a filename
 677 relative to the object file containing the \dotdebugsup{} section.
 678 If \addttindex{is\_supplementary} is 1, then \addttindex{sup\_filename}
 679 is not needed and must be an empty string (a single null byte).
 680
 681 \needlines{4}
 682 \item \texttt{sup\_checksum\_len} (unsigned LEB128) \\
 683 \addttindexx{sup\_checksum\_len}
 684 Length of the following \addttindex{sup\_checksum} field;
 685 this value can be 0 if no checksum is provided.
 686
 687 \item \texttt{sup\_checksum} (array of \HFTubyte) \\
 688 \addttindexx{sup\_checksum}
 689 An implementation-defined integer constant value that
 690 provides unique identification of the supplementary file.
 691
 692 \end{enumerate}
 693
 694 Debug information entries that refer to an executable's or shared
 695 object's addresses must \emph{not} be moved to supplementary files
 696 (the addesses will likely not be the same). Similarly,
 697 entries referenced from within location descriptions or using loclistsptr
 698 form attributes must not be moved to a \addtoindex{supplementary object file}.
 699
 700 Executable or shared object file compilation units can use
 701 \DWTAGimportedunit{} with
 702 \bb
 703 an \DWATimport{} attribute that uses \DWFORMrefsupfour{} or \DWFORMrefsupeight{}
 704 \eb
 705 to import entries from the \addtoindex{supplementary object file}, other
 706 \bb
 707 \DWFORMrefsupfour{} or \DWFORMrefsupeight{}
 708 \eb
 709 attributes to refer to them and \DWFORMstrpsup{} form attributes to
 710 refer to strings that are used by debug information of multiple
 711 executables or shared object files.  Within the \addtoindex{supplementary object file}'s
 712 debugging sections, form
 713 \bb
 714 \DWFORMrefsupfour{}, \DWFORMrefsupeight{}
 715 \eb
 716 or \DWFORMstrpsup{} are
 717 not used, and all reference forms referring to some other sections
 718 refer to the local sections in the \addtoindex{supplementary object file}.
 719
 720 In macro information, \DWMACROdefinesup{} or
 721 \DWMACROundefsup{} opcodes can refer to strings in the
 722 \dotdebugstr{} section of the \addtoindex{supplementary object file},
 723 or \DWMACROimportsup{}
 724 can refer to \dotdebugmacro{} section entries.  Within the
 725 \dotdebugmacro{} section of a \addtoindex{supplementary object file},
 726 \DWMACROdefinestrp{} and \DWMACROundefstrp{}
 727 opcodes refer to the local \dotdebugstr{} section in that
 728 supplementary file, not the one in
 729 the executable or shared object file.
 730
 731
 732 \needlines{6}
 733 \section{32-Bit and 64-Bit DWARF Formats}
 734 \label{datarep:32bitand64bitdwarfformats}
 735 \hypertarget{datarep:xxbitdwffmt}{}
 736 \addtoindexx{32-bit DWARF format}
 737 \addtoindexx{64-bit DWARF format}
 738 There are two closely-related DWARF
 739 formats. In the 32-bit DWARF
 740 format, all values that represent lengths of DWARF sections
 741 and offsets relative to the beginning of DWARF sections are
 742 represented using four bytes. In the 64-bit DWARF format, all
 743 values that represent lengths of DWARF sections and offsets
 744 relative to the beginning of DWARF sections are represented
 745 using eight bytes. A special convention applies to the initial
 746 length field of certain DWARF sections, as well as the CIE and
 747 FDE structures, so that the 32-bit and 64-bit DWARF formats
 748 can coexist and be distinguished within a single linked object.
 749
 750 Except where noted otherwise, all references in this document
 751 to a debugging information section (for example, \dotdebuginfo),
 752 apply also to the corresponding split DWARF section (for example,
 753 \dotdebuginfodwo).
 754
 755 The differences between the 32- and 64-bit DWARF formats are
 756 detailed in the following:
 757 \begin{enumerate}[1. ]
 758
 759 \item  In the 32-bit DWARF format, an
 760 \addtoindex{initial length} field (see
 761 \addtoindexx{initial length!encoding}
 762 Section \ref{datarep:initiallengthvalues} on page \pageref{datarep:initiallengthvalues})
 763 is an unsigned 4-byte integer (which
 764 must be less than \xfffffffzero); in the 64-bit DWARF format,
 765 an \addtoindex{initial length} field is 12 bytes in size,
 766 and has two parts:
 767 \begin{itemize}
 768 \item The first four bytes have the value \xffffffff.
 769
 770 \item  The following eight bytes contain the actual length
 771 represented as an unsigned 8-byte integer.
 772 \end{itemize}
 773
 774 \textit{This representation allows a DWARF consumer to dynamically
 775 detect that a DWARF section contribution is using the 64-bit
 776 format and to adapt its processing accordingly.}
 777
 778 \needlines{4}
 779 \item \hypertarget{datarep:sectionoffsetlength}{}
 780 Section offset and section length
 781 \addtoindexx{section length!use in headers}
 782 fields that occur
 783 \addtoindexx{section offset!use in headers}
 784 in the headers of DWARF sections (other than initial length
 785 \addtoindexx{initial length}
 786 fields) are listed following. In the 32-bit DWARF format these
 787 are 4-byte unsigned integer values; in the 64-bit DWARF format,
 788 they are 8-byte unsigned integer values.
 789
 790 \begin{nolinenumbersenv}
 791 \begin{center}
 792 \begin{tabular}{lll}
 793 Section &Name & Role  \\ \hline
 794 \dotdebugaranges{}   & \addttindex{debug\_info\_offset}   & offset in \dotdebuginfo{} \\
 795 \dotdebugframe{}/CIE & \addttindex{CIE\_id}               & CIE distinguished value \\
 796 \dotdebugframe{}/FDE & \addttindex{CIE\_pointer}          & offset in \dotdebugframe{} \\
 797 \dotdebuginfo{}      & \addttindex{debug\_abbrev\_offset} & offset in \dotdebugabbrev{} \\
 798 \dotdebugline{}      & \addttindex{header\_length}        & length of header itself \\
 799 \dotdebugnames{}     & entry in array of CUs              & offset in \dotdebuginfo{} \\
 800                      & or local TUs                       & \\
 801 \end{tabular}
 802 \end{center}
 803 \end{nolinenumbersenv}
 804
 805 \needlines{4}
 806 The \texttt{CIE\_id} field in a CIE structure must be 64 bits because
 807 it overlays the \texttt{CIE\_pointer} in a FDE structure; this implicit
 808 union must be accessed to distinguish whether a CIE or FDE is
 809 present, consequently, these two fields must exactly overlay
 810 each other (both offset and size).
 811
 812 \item Within the body of the \dotdebuginfo{}
 813 section, certain forms of attribute value depend on the choice
 814 of DWARF format as follows. For the 32-bit DWARF format,
 815 the value is a 4-byte unsigned integer; for the 64-bit DWARF
 816 format, the value is an 8-byte unsigned integer.
 817
 818 \begin{center}
 819 \begin{nolinenumbersenv}
 820 \begin{tabular}{lp{6cm}}
 821 Form             & Role  \\ \hline
 822 \DWFORMlinestrp  & offset in \dotdebuglinestr \\
 823 \DWFORMrefaddr   & offset in \dotdebuginfo{} \\
 824 \bbeb
 825 \DWFORMsecoffset & offset in a section other than \\
 826                  & \dotdebuginfo{} or \dotdebugstr{} \\
 827 \DWFORMstrp      & offset in \dotdebugstr{} \\
 828 \DWFORMstrpsup   & offset in \dotdebugstr{} section of a \mbox{supplementary} object file \\
 829 \DWOPcallref     & offset in \dotdebuginfo{} \\
 830 \end{tabular}
 831 \end{nolinenumbersenv}
 832 \end{center}
 833
 834 \needlines{5}
 835 \item Within the body of the \dotdebugline{} section, certain forms of content
 836 description depend on the choice of DWARF format as follows: for the
 837 32-bit DWARF format, the value is a 4-byte unsigned integer; for the
 838 64-bit DWARF format, the value is a 8-byte unsigned integer.
 839
 840 \begin{center}
 841 \begin{nolinenumbersenv}
 842 \begin{tabular}{lp{6cm}}
 843 Form             & Role  \\ \hline
 844 \DWFORMlinestrp  & offset in \dotdebuglinestr
 845 \end{tabular}
 846 \end{nolinenumbersenv}
 847 \end{center}
 848
 849 \item Within the body of the \dotdebugnames{}
 850 sections, the representation of each entry in the array of
 851 compilation units (CUs) and the array of local type units
 852 (TUs), which represents an offset in the
 853 \dotdebuginfo{}
 854 section, depends on the DWARF format as follows: in the
 855 32-bit DWARF format, each entry is a 4-byte unsigned integer;
 856 in the 64-bit DWARF format, it is a 8-byte unsigned integer.
 857
 858 \needlines{4}
 859 \item In the body of the \dotdebugstroffsets{}
 860 sections, the size of entries in the body depend on the DWARF
 861 format as follows: in the 32-bit DWARF format, entries are 4-byte
 862 unsigned integer values; in the 64-bit DWARF format, they are
 863 8-byte unsigned integers.
 864
 865 %\bbpareb-delete bullet 7
 866
 867 \item In the body of the \dotdebugloclists{} and \dotdebugrnglists{}
 868 sections, the offsets the follow the header depend on the
 869 DWARF format as follows: in the 32-bit DWARF format, offsets are 4-byte
 870 unsigned integer values; in the 64-bit DWARF format, they are
 871 8-byte unsigned integers.
 872
 873 \end{enumerate}
 874
 875
 876 The 32-bit and 64-bit DWARF format conventions must \emph{not} be
 877 intermixed within a single compilation unit.
 878
 879 \textit{Attribute values and section header fields that represent
 880 addresses in the target program are not affected by these
 881 rules.}
 882
 883 \needlines{6}
 884 A DWARF consumer that supports the 64-bit DWARF format must
 885 support executables in which some compilation units use the
 886 32-bit format and others use the 64-bit format provided that
 887 the combination links correctly (that is, provided that there
 888 are no link\dash time errors due to truncation or overflow). (An
 889 implementation is not required to guarantee detection and
 890 reporting of all such errors.)
 891
 892 \textit{It is expected that DWARF producing compilers will \emph{not} use
 893 the 64-bit format \emph{by default}. In most cases, the division of
 894 even very large applications into a number of executable and
 895 shared object files will suffice to assure that the DWARF sections
 896 within each individual linked object are less than 4 GBytes
 897 in size. However, for those cases where needed, the 64-bit
 898 format allows the unusual case to be handled as well. Even
 899 in this case, it is expected that only application supplied
 900 objects will need to be compiled using the 64-bit format;
 901 separate 32-bit format versions of system supplied shared
 902 executable libraries can still be used.}
 903
 904
 905 \section{Format of Debugging Information}
 906 \label{datarep:formatofdebugginginformation}
 907
 908 For each compilation unit compiled with a DWARF producer,
 909 a contribution is made to the \dotdebuginfo{} section of
 910 the object file. Each such contribution consists of a
 911 compilation unit header
 912 (see Section \refersec{datarep:compilationunitheader})
 913 followed by a
 914 single \DWTAGcompileunit{} or
 915 \DWTAGpartialunit{} debugging
 916 information entry, together with its children.
 917
 918 For each type defined in a compilation unit, a separate
 919 contribution may also be made to the
 920 \dotdebuginfo{}
 921 section of the object file. Each
 922 such contribution consists of a
 923 \addtoindex{type unit} header
 924 (see Section \refersec{datarep:typeunitheaders})
 925 followed by a \DWTAGtypeunit{} entry, together with
 926 its children.
 927
 928 Each debugging information entry begins with a code that
 929 represents an entry in a separate
 930 \addtoindex{abbreviations table}. This
 931 code is followed directly by a series of attribute values.
 932
 933 The appropriate entry in the
 934 \addtoindex{abbreviations table} guides the
 935 interpretation of the information contained directly in the
 936 \dotdebuginfo{} section.
 937
 938 Multiple debugging information entries may share the same
 939 abbreviation table entry. Each compilation unit is associated
 940 with a particular abbreviation table, but multiple compilation
 941 units may share the same table.
 942
 943 \needlines{6}
 944 \subsection{Unit Headers}
 945 \label{datarep:unitheaders}
 946 Unit headers contain a field, \addttindex{unit\_type}, whose value indicates the kind of
 947 compilation unit
 948 \bb
 949 (see Section \ref{chap:unitentries})
 950 \eb
 951 that follows. The encodings for the unit type
 952 enumeration are shown in Table \refersec{tab:unitheaderunitkindencodings}.
 953
 954 \needlines{6}
 955 \begin{centering}
 956 \setlength{\extrarowheight}{0.1cm}
 957 \begin{longtable}{l|c}
 958   \caption{Unit header unit type encodings}
 959   \label{tab:unitheaderunitkindencodings}
 960   \addtoindexx{unit header unit type encodings} \\
 961   \hline \bfseries Unit header unit type encodings&\bfseries Value \\ \hline
 962 \endfirsthead
 963   \bfseries Unit header unit type encodings&\bfseries Value \\ \hline
 964 \endhead
 965   \hline \emph{Continued on next page}
 966 \endfoot
 967   \hline \ddag\ \textit{New in DWARF Version 5}
 968 \endlastfoot
 969 \DWUTcompileTARG~\ddag      &0x01 \\
 970 \DWUTtypeTARG~\ddag         &0x02 \\
 971 \DWUTpartialTARG~\ddag      &0x03 \\
 972 \DWUTskeletonTARG~\ddag     &0x04 \\
 973 \DWUTsplitcompileTARG~\ddag &0x05 \\
 974 \DWUTsplittypeTARG~\ddag    &0x06 \\
 975 \DWUTlouserTARG~\ddag       &0x80 \\
 976 \DWUThiuserTARG~\ddag       &\xff \\
 977 \hline
 978 \end{longtable}
 979 \end{centering}
 980
 981 \bb
 982 All unit headers have the same initial three fields.
 983 \eb
 984
 985
 986 \needlines{5}
 987 \bb
 988 \subsubsection{Full and Partial Compilation Unit Headers}
 989 \eb
 990 \label{datarep:compilationunitheader}
 991 \begin{enumerate}[1. ]
 992
 993 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
 994 \addttindexx{unit\_length}
 995 A 4-byte or 12-byte
 996 \addtoindexx{initial length}
 997 unsigned integer representing the length
 998 of the \dotdebuginfo{} contribution for that compilation unit,
 999 not including the length field itself. In the \thirtytwobitdwarfformat,
1000 this is a 4-byte unsigned integer (which must be less
1001 than \xfffffffzero); in the \sixtyfourbitdwarfformat, this consists
1002 of the 4-byte value \wffffffff followed by an 8-byte unsigned
1003 integer that gives the actual length
1004 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1005
1006 \item  \texttt{version} (\HFTuhalf) \\
1007 \addttindexx{version}
1008 \addtoindexx{version number!compilation unit}
1009 A 2-byte unsigned integer representing the version of the
1010 DWARF information for the compilation unit.
1011
1012 The value in this field is \versiondotdebuginfo.
1013
1014 \textit{See also Appendix \refersec{app:dwarfsectionversionnumbersinformative}
1015 for a summary of all version numbers that apply to DWARF sections.}
1016
1017 \needlines{4}
1018 \item \texttt{unit\_type} (\HFTubyte) \\
1019 \addttindexx{unit\_type}
1020 A 1-byte unsigned integer identifying this unit as a compilation unit.
1021 The value of this field is
1022 \DWUTcompile{} for a
1023 \bb
1024 (non-split) full compilation unit or
1025 \DWUTpartial{} for a (non-split) partial compilation unit
1026 \eb
1027 (see Section \refersec{chap:fullandpartialcompilationunitentries}).
1028
1029 \textit{See
1030 \bb
1031 Section \ref{datarep:skeletonandfullcompilationunitheaders}
1032 regarding a split full compilation unit.
1033 \eb}
1034
1035 \textit{This field is new in \DWARFVersionV.}
1036
1037 \needlines{4}
1038 \item \texttt{address\_size} (\HFTubyte) \\
1039 \addttindexx{address\_size}
1040 A 1-byte unsigned integer representing the size in bytes of
1041 an address on the target architecture. If the system uses
1042 \addtoindexx{address space!segmented}
1043 segmented addressing, this value represents the size of the
1044 offset portion of an address.
1045
1046 \item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
1047 A
1048 \addtoindexx{section offset!in .debug\_info header}
1049 4-byte or 8-byte unsigned offset into the
1050 \dotdebugabbrev{}
1051 section. This offset associates the compilation unit with a
1052 particular set of debugging information entry abbreviations. In
1053 the \thirtytwobitdwarfformat, this is a 4-byte unsigned length;
1054 in the \sixtyfourbitdwarfformat, this is an 8-byte unsigned length
1055 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1056
1057 \bbpareb
1058 \end{enumerate}
1059
1060 \needlines{8}
1061 \subsubsection{Skeleton and Split Compilation Unit Headers}
1062 \label{datarep:skeletonandfullcompilationunitheaders}
1063 \begin{enumerate}[1. ]
1064
1065 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
1066 \addttindexx{unit\_length}
1067 A 4-byte or 12-byte
1068 \addtoindexx{initial length}
1069 unsigned integer representing the length
1070 of the \dotdebuginfo{}
1071 contribution for that compilation unit,
1072 not including the length field itself. In the \thirtytwobitdwarfformat,
1073 this is a 4-byte unsigned integer (which must be less
1074 than \xfffffffzero); in the \sixtyfourbitdwarfformat, this consists
1075 of the 4-byte value \wffffffff followed by an 8-byte unsigned
1076 integer that gives the actual length
1077 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1078
1079 \item  \texttt{version} (\HFTuhalf) \\
1080 \addttindexx{version}
1081 \addtoindexx{version number!compilation unit}
1082 A 2-byte unsigned integer representing the version of the
1083 DWARF information for the compilation unit.
1084
1085 The value in this field is \versiondotdebuginfo.
1086
1087 \textit{See also Appendix \refersec{app:dwarfsectionversionnumbersinformative}
1088 for a summary of all version numbers that apply to DWARF sections.}
1089
1090 \needlines{4}
1091 \item \texttt{unit\_type} (\HFTubyte) \\
1092 \addttindexx{unit\_type}
1093 A 1-byte unsigned integer identifying this unit as a compilation unit.
1094 The value of this field is
1095 \DWUTskeleton{} for a skeleton compilation unit or
1096 \DWUTsplitcompile{} for a split
1097 \bb
1098 (full)
1099 \eb
1100 compilation unit
1101 (see Section \refersec{chap:skeletoncompilationunitentries}).
1102
1103 \textit{There
1104 \bb
1105 is no split analog to the partial compilation unit.
1106 \eb}
1107
1108 \textit{This field is new in \DWARFVersionV.}
1109
1110 \needlines{4}
1111 \item \texttt{address\_size} (\HFTubyte) \\
1112 \addttindexx{address\_size}
1113 A 1-byte unsigned integer representing the size in bytes of
1114 an address on the target architecture. If the system uses
1115 \addtoindexx{address space!segmented}
1116 segmented addressing, this value represents the size of the
1117 offset portion of an address.
1118
1119 \item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
1120 A
1121 \addtoindexx{section offset!in .debug\_info header}
1122 4-byte or 8-byte unsigned offset into the
1123 \dotdebugabbrev{}
1124 section. This offset associates the compilation unit with a
1125 particular set of debugging information entry abbreviations. In
1126 the \thirtytwobitdwarfformat, this is a 4-byte unsigned length;
1127 in the \sixtyfourbitdwarfformat, this is an 8-byte unsigned length
1128 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1129
1130 \needlines{6}
1131 \item \HFNdwoid{} (unit ID) \\
1132 An 8-byte implementation-defined integer constant value,
1133 known as the compilation unit ID, that provides
1134 unique identification of a skeleton compilation
1135 unit and its associated split compilation unit in
1136 the object file named in the \DWATdwoname{} attribute
1137 of the skeleton compilation.
1138
1139 \bbpareb
1140 \end{enumerate}
1141
1142 \needlines{8}
1143 \subsubsection{Type Unit Headers}
1144 \label{datarep:typeunitheaders}
1145 The header for the series of debugging information entries
1146 contributing to the description of a type that has been
1147 placed in its own \addtoindex{type unit}, within the
1148 \dotdebuginfo{} section,
1149 consists of the following information:
1150 \begin{enumerate}[1. ]
1151 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
1152 \addttindexx{unit\_length}
1153 A 4-byte or 12-byte unsigned integer
1154 \addtoindexx{initial length}
1155 representing the length
1156 of the \dotdebuginfo{} contribution for that type unit,
1157 not including the length field itself. In the \thirtytwobitdwarfformat,
1158 this is a 4-byte unsigned integer (which must be
1159 less than \xfffffffzero); in the \sixtyfourbitdwarfformat, this
1160 consists of the 4-byte value \wffffffff followed by an
1161 8-byte unsigned integer that gives the actual length
1162 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1163
1164 \needlines{4}
1165 \item  \texttt{version} (\HFTuhalf) \\
1166 \addttindexx{version}
1167 \addtoindexx{version number!type unit}
1168 A 2-byte unsigned integer representing the version of the
1169 DWARF information for the type unit.
1170
1171 The value in this field is \versiondotdebuginfo.
1172
1173 \item \texttt{unit\_type} (\HFTubyte) \\
1174 \addttindexx{unit\_type}
1175 A 1-byte unsigned integer identifying this unit as a type unit.
1176 The value of this field is \DWUTtype{} for a non-split type unit
1177 (see Section \refersec{chap:typeunitentries})
1178 or \DWUTsplittype{} for a split type unit.
1179
1180 \textit{This field is new in \DWARFVersionV.}
1181
1182 \needlines{4}
1183 \item \texttt{address\_size} (\HFTubyte) \\
1184 \addttindexx{address\_size}
1185 A 1-byte unsigned integer representing the size
1186 \addtoindexx{size of an address}
1187 in bytes of
1188 an address on the target architecture. If the system uses
1189 \addtoindexx{address space!segmented}
1190 segmented addressing, this value represents the size of the
1191 offset portion of an address.
1192
1193 %\needlines{6}
1194 \item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
1195 A
1196 \addtoindexx{section offset!in .debug\_info header}
1197 4-byte or 8-byte unsigned offset into the
1198 \dotdebugabbrev{}
1199 section. This offset associates the type unit with a
1200 particular set of debugging information entry abbreviations. In
1201 the \thirtytwobitdwarfformat, this is a 4-byte unsigned length;
1202 in the \sixtyfourbitdwarfformat, this is an 8-byte unsigned length
1203 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1204
1205 \item \texttt{type\_signature} (8-byte unsigned integer) \\
1206 \addttindexx{type\_signature}
1207 \addtoindexx{type signature}
1208 A unique 8-byte signature (see Section
1209 \refersec{datarep:typesignaturecomputation})
1210 of the type described in this type
1211 unit.
1212
1213 \textit{An attribute that refers (using
1214 \DWFORMrefsigeight{}) to
1215 the primary type contained in this
1216 \addtoindex{type unit} uses this value.}
1217
1218 %\needlines{8}
1219 \item \texttt{type\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
1220 \addttindexx{type\_offset}
1221 A 4-byte or 8-byte unsigned offset
1222 \addtoindexx{section offset!in .debug\_info header}
1223 relative to the beginning
1224 of the \addtoindex{type unit} header.
1225 This offset refers to the debugging
1226 information entry that describes the type. Because the type
1227 may be nested inside a namespace or other structures, and may
1228 contain references to other types that have not been placed in
1229 separate type units, it is not necessarily either the first or
1230 the only entry in the type unit. In the \thirtytwobitdwarfformat,
1231 this is a 4-byte unsigned length; in the \sixtyfourbitdwarfformat,
1232 this is an 8-byte unsigned length
1233 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1234
1235 \end{enumerate}
1236
1237 \subsection{Debugging Information Entry}
1238 \label{datarep:debugginginformationentry}
1239
1240 Each debugging information entry begins with an
1241 unsigned LEB128\addtoindexx{LEB128!unsigned}
1242 number containing the abbreviation code for the entry. This
1243 code represents an entry within the abbreviations table
1244 associated with the compilation unit containing this entry. The
1245 abbreviation code is followed by a series of attribute values.
1246
1247 On some architectures, there are alignment constraints on
1248 section boundaries. To make it easier to pad debugging
1249 information sections to satisfy such constraints, the
1250 abbreviation code 0 is reserved. Debugging information entries
1251 consisting of only the abbreviation code 0 are considered
1252 null entries.
1253
1254 \subsection{Abbreviations Tables}
1255 \label{datarep:abbreviationstables}
1256 The abbreviations tables for all compilation units
1257 are contained in a separate object file section called
1258 \dotdebugabbrev{}.
1259 As mentioned before, multiple compilation
1260 units may share the same abbreviations table.
1261
1262 The abbreviations table for a single compilation unit consists
1263 of a series of abbreviation declarations. Each declaration
1264 specifies the tag and attributes for a particular form of
1265 debugging information entry. Each declaration begins with
1266 an unsigned LEB128\addtoindexx{LEB128!unsigned}
1267 number representing the abbreviation
1268 code itself. It is this code that appears at the beginning
1269 of a debugging information entry in the
1270 \dotdebuginfo{}
1271 section. As described above, the abbreviation
1272 code 0 is reserved for null debugging information entries. The
1273 abbreviation code is followed by another unsigned LEB128\addtoindexx{LEB128!unsigned}
1274 number that encodes the entry\textquoteright s tag. The encodings for the
1275 tag names are given in
1276 Table \refersec{tab:tagencodings}.
1277
1278 \needlines{10}
1279 \begin{centering}
1280 \setlength{\extrarowheight}{0.1cm}
1281 \begin{longtable}{l|c}
1282   \caption{Tag encodings} \label{tab:tagencodings} \\
1283   \hline \bfseries Tag name&\bfseries Value\\ \hline
1284 \endfirsthead
1285   \bfseries Tag name&\bfseries Value \\ \hline
1286 \endhead
1287   \hline \emph{Continued on next page}
1288 \endfoot
1289   \hline \ddag\ \textit{New in DWARF Version 5}
1290 \endlastfoot
1291 \DWTAGarraytype{} &0x01 \\
1292 \DWTAGclasstype&0x02 \\
1293 \DWTAGentrypoint&0x03 \\
1294 \DWTAGenumerationtype&0x04 \\
1295 \DWTAGformalparameter&0x05 \\
1296 \bbeb\textit{Reserved}&0x06 \\
1297 \bbeb\textit{Reserved}&0x07 \\
1298 \DWTAGimporteddeclaration&0x08 \\
1299 \bbeb\textit{Reserved}&0x09 \\
1300 \DWTAGlabel&0x0a \\
1301 \DWTAGlexicalblock&0x0b \\
1302 \bbeb\textit{Reserved}&0x0c \\
1303 \DWTAGmember&0x0d \\
1304 \bbeb\textit{Reserved}&0x0e \\
1305 \DWTAGpointertype&0x0f \\
1306 \DWTAGreferencetype&0x10 \\
1307 \DWTAGcompileunit&0x11 \\
1308 \DWTAGstringtype&0x12 \\
1309 \DWTAGstructuretype&0x13 \\
1310 \bbeb\textit{Reserved}&0x14 \\
1311 \DWTAGsubroutinetype&0x15 \\
1312 \DWTAGtypedef&0x16 \\
1313 \DWTAGuniontype&0x17 \\
1314 \DWTAGunspecifiedparameters&0x18  \\
1315 \DWTAGvariant&0x19  \\
1316 \DWTAGcommonblock&0x1a  \\
1317 \DWTAGcommoninclusion&0x1b  \\
1318 \DWTAGinheritance&0x1c  \\
1319 \DWTAGinlinedsubroutine&0x1d  \\
1320 \DWTAGmodule&0x1e  \\
1321 \DWTAGptrtomembertype&0x1f  \\
1322 \DWTAGsettype&0x20  \\
1323 \DWTAGsubrangetype&0x21  \\
1324 \DWTAGwithstmt&0x22  \\
1325 \DWTAGaccessdeclaration&0x23  \\
1326 \DWTAGbasetype&0x24  \\
1327 \DWTAGcatchblock&0x25  \\
1328 \DWTAGconsttype&0x26  \\
1329 \DWTAGconstant&0x27  \\
1330 \DWTAGenumerator&0x28  \\
1331 \DWTAGfiletype&0x29  \\
1332 \DWTAGfriend&0x2a  \\
1333 \DWTAGnamelist&0x2b    \\
1334 \DWTAGnamelistitem&0x2c    \\
1335 \DWTAGpackedtype&0x2d    \\
1336 \DWTAGsubprogram&0x2e    \\
1337 \DWTAGtemplatetypeparameter&0x2f    \\
1338 \DWTAGtemplatevalueparameter&0x30    \\
1339 \DWTAGthrowntype&0x31    \\
1340 \DWTAGtryblock&0x32    \\
1341 \DWTAGvariantpart&0x33    \\
1342 \DWTAGvariable&0x34    \\
1343 \DWTAGvolatiletype&0x35    \\
1344 \DWTAGdwarfprocedure&0x36     \\
1345 \DWTAGrestricttype&0x37      \\
1346 \DWTAGinterfacetype&0x38      \\
1347 \DWTAGnamespace&0x39      \\
1348 \DWTAGimportedmodule&0x3a      \\
1349 \DWTAGunspecifiedtype&0x3b      \\
1350 \DWTAGpartialunit&0x3c      \\
1351 \DWTAGimportedunit&0x3d      \\
1352 \textit{Reserved}&0x3e\footnote{Code 0x3e is reserved to allow backward compatible support of the
1353 DW\_TAG\_mutable\_type DIE that was defined (only) in \DWARFVersionIII.}
1354 \\
1355 \DWTAGcondition&\xiiif      \\
1356 \DWTAGsharedtype&0x40      \\
1357 \DWTAGtypeunit & 0x41      \\
1358 \DWTAGrvaluereferencetype & 0x42      \\
1359 \DWTAGtemplatealias & 0x43      \\
1360 \DWTAGcoarraytype~\ddag & 0x44 \\
1361 \DWTAGgenericsubrange~\ddag & 0x45 \\
1362 \DWTAGdynamictype~\ddag & 0x46 \\
1363 \DWTAGatomictype~\ddag & 0x47 \\
1364 \DWTAGcallsite~\ddag & 0x48 \\
1365 \DWTAGcallsiteparameter~\ddag & 0x49 \\
1366 \DWTAGskeletonunit~\ddag & 0x4a \\
1367 \DWTAGimmutabletype~\ddag & 0x4b \\
1368 \DWTAGlouser&0x4080      \\
1369 \DWTAGhiuser&\xffff      \\
1370 \end{longtable}
1371 \end{centering}
1372
1373 \needlines{8}
1374 Following the tag encoding is a 1-byte value that determines
1375 whether a debugging information entry using this abbreviation
1376 has child entries or not. If the value is
1377 \DWCHILDRENyesTARG,
1378 the next physically succeeding entry of any debugging
1379 information entry using this abbreviation is the first
1380 child of that entry. If the 1-byte value following the
1381 abbreviation\textquoteright s tag encoding is
1382 \DWCHILDRENnoTARG, the next
1383 physically succeeding entry of any debugging information entry
1384 using this abbreviation is a sibling of that entry. (Either
1385 the first child or sibling entries may be null entries). The
1386 encodings for the child determination byte are given in
1387 Table \refersec{tab:childdeterminationencodings}
1388 (As mentioned in
1389 Section \refersec{chap:relationshipofdebugginginformationentries},
1390 each chain of sibling entries is terminated by a null entry.)
1391
1392 \needlines{6}
1393 \begin{centering}
1394 \setlength{\extrarowheight}{0.1cm}
1395 \begin{longtable}{l|c}
1396   \caption{Child determination encodings}
1397   \label{tab:childdeterminationencodings}
1398   \addtoindexx{Child determination encodings} \\
1399   \hline \bfseries Children determination name&\bfseries Value \\ \hline
1400 \endfirsthead
1401   \bfseries Children determination name&\bfseries Value \\ \hline
1402 \endhead
1403   \hline \emph{Continued on next page}
1404 \endfoot
1405   \hline
1406 \endlastfoot
1407 \DWCHILDRENno&0x00 \\
1408 \DWCHILDRENyes&0x01 \\ \hline
1409 \end{longtable}
1410 \end{centering}
1411
1412 \needlines{4}
1413 Finally, the child encoding is followed by a series of
1414 attribute specifications. Each attribute specification
1415 consists of two parts. The first part is an
1416 unsigned LEB128\addtoindexx{LEB128!unsigned}
1417 number representing the attribute\textquoteright s name.
1418 The second part is an
1419 unsigned LEB128\addtoindexx{LEB128!unsigned}
1420 number representing the attribute\textquoteright s form.
1421 The series of attribute specifications ends with an
1422 entry containing 0 for the name and 0 for the form.
1423
1424 \needlines{4}
1425 The attribute form
1426 \DWFORMindirectTARG{} is a special case. For
1427 attributes with this form, the attribute value itself in the
1428 \dotdebuginfo{}
1429 section begins with an unsigned
1430 LEB128 number that represents its form. This allows producers
1431 to choose forms for particular attributes
1432 \addtoindexx{abbreviations table!dynamic forms in}
1433 dynamically,
1434 without having to add a new entry to the abbreviations table.
1435
1436 The attribute form \DWFORMimplicitconstTARG{} is another special case.
1437 For attributes with this form, the attribute specification contains
1438 a third part, which is a signed LEB128\addtoindexx{LEB128!signed}
1439 number. The value of this number is used as the value of the
1440 attribute, and no value is stored in the \dotdebuginfo{} section.
1441
1442 The abbreviations for a given compilation unit end with an
1443 entry consisting of a 0 byte for the abbreviation code.
1444
1445 \textit{See
1446 Appendix \refersec{app:compilationunitsandabbreviationstableexample}
1447 for a depiction of the organization of the
1448 debugging information.}
1449
1450 \needlines{12}
1451 \subsection{Attribute Encodings}
1452 \label{datarep:attributeencodings}
1453
1454 The encodings for the attribute names are given in
1455 Table \referfol{tab:attributeencodings}.
1456
1457 \begin{centering}
1458 \setlength{\extrarowheight}{0.1cm}
1459 \begin{longtable}{l|c|l}
1460   \caption{Attribute encodings}
1461   \label{tab:attributeencodings}
1462   \addtoindexx{attribute encodings} \\
1463   \hline \bfseries Attribute name&\bfseries Value &\bfseries Classes \\ \hline
1464 \endfirsthead
1465   \bfseries Attribute name&\bfseries Value &\bfseries Classes\\ \hline
1466 \endhead
1467   \hline \emph{Continued on next page}
1468 \endfoot
1469   \hline \ddag\ \textit{New in DWARF Version 5}
1470 \endlastfoot
1471 \DWATsibling&0x01&\livelink{chap:classreference}{reference}
1472             \addtoindexx{sibling attribute} \\
1473 \DWATlocation&0x02&\livelink{chap:classexprloc}{exprloc},
1474         \CLASSloclist
1475             \addtoindexx{location attribute}   \\
1476 \DWATname&0x03&\livelink{chap:classstring}{string}
1477             \addtoindexx{name attribute} \\
1478 \bbeb\textit{Reserved}&0x04&\textit{not applicable} \\
1479 \bbeb\textit{Reserved}&0x05&\textit{not applicable} \\
1480 \bbeb\textit{Reserved}&0x06&\textit{not applicable} \\
1481 \bbeb\textit{Reserved}&0x07&\textit{not applicable} \\
1482 \bbeb\textit{Reserved}&0x08&\textit{not applicable} \\
1483 \DWATordering&0x09&\livelink{chap:classconstant}{constant}
1484             \addtoindexx{ordering attribute}  \\
1485 \bbeb\textit{Reserved}&0x0a&\textit{not applicable} \\
1486 \DWATbytesize&0x0b&\livelink{chap:classconstant}{constant},
1487         \livelink{chap:classexprloc}{exprloc},
1488         \livelink{chap:classreference}{reference}
1489             \addtoindexx{byte size attribute} \\
1490 \textit{Reserved}&0x0c\footnote{Code 0x0c is reserved to allow backward compatible support of the
1491              DW\_AT\_bit\_offset \mbox{attribute} which was
1492              defined in \DWARFVersionIII{} and earlier.}
1493        &\livelink{chap:classconstant}{constant},
1494         \livelink{chap:classexprloc}{exprloc},
1495         \livelink{chap:classreference}{reference}
1496             \addtoindexx{bit offset attribute (Version 3)}
1497             \addtoindexx{DW\_AT\_bit\_offset (deprecated)}  \\
1498 \DWATbitsize&0x0d&\livelink{chap:classconstant}{constant},
1499         \livelink{chap:classexprloc}{exprloc},
1500         \livelink{chap:classreference}{reference}
1501             \addtoindexx{bit size attribute} \\
1502 \bbeb\textit{Reserved}&0x0e&\textit{not applicable} \\
1503 \bbeb\textit{Reserved}&0x0f&\textit{not applicable} \\
1504 \DWATstmtlist&0x10&\livelink{chap:classlineptr}{lineptr}
1505             \addtoindexx{statement list attribute} \\
1506 \DWATlowpc&0x11&\livelink{chap:classaddress}{address}
1507             \addtoindexx{low PC attribute}  \\
1508 \DWAThighpc&0x12&\livelink{chap:classaddress}{address},
1509         \livelink{chap:classconstant}{constant}
1510             \addtoindexx{high PC attribute}  \\
1511 \DWATlanguage&0x13&\livelink{chap:classconstant}{constant}
1512             \addtoindexx{language attribute}  \\
1513 \bbeb\textit{Reserved}&0x14&\textit{not applicable} \\
1514 \DWATdiscr&0x15&\livelink{chap:classreference}{reference}
1515             \addtoindexx{discriminant attribute}  \\
1516 \DWATdiscrvalue&0x16&\livelink{chap:classconstant}{constant}
1517             \addtoindexx{discriminant value attribute}  \\
1518 \DWATvisibility&0x17&\livelink{chap:classconstant}{constant}
1519             \addtoindexx{visibility attribute} \\
1520 \DWATimport&0x18&\livelink{chap:classreference}{reference}
1521             \addtoindexx{import attribute}  \\
1522 \DWATstringlength&0x19&\livelink{chap:classexprloc}{exprloc},
1523         \CLASSloclist,
1524 \bbeb   \CLASSreference
1525         \addtoindexx{string length attribute}  \\
1526 \DWATcommonreference&0x1a&\livelink{chap:classreference}{reference}
1527             \addtoindexx{common reference attribute}  \\
1528 \DWATcompdir&0x1b&\livelink{chap:classstring}{string}
1529             \addtoindexx{compilation directory attribute}  \\
1530 \DWATconstvalue&0x1c&\livelink{chap:classblock}{block},
1531         \livelink{chap:classconstant}{constant},
1532         \livelink{chap:classstring}{string}
1533             \addtoindexx{constant value attribute} \\
1534 \DWATcontainingtype&0x1d&\livelink{chap:classreference}{reference}
1535             \addtoindexx{containing type attribute} \\
1536 \DWATdefaultvalue&0x1e&\livelink{chap:classconstant}{constant},
1537         \livelink{chap:classreference}{reference},
1538         \livelink{chap:classflag}{flag}
1539             \addtoindexx{default value attribute} \\
1540 \bbeb\textit{Reserved}&0x1f&\textit{not applicable} \\
1541 \DWATinline&0x20&\livelink{chap:classconstant}{constant}
1542             \addtoindexx{inline attribute}  \\
1543 \DWATisoptional&0x21&\livelink{chap:classflag}{flag}
1544             \addtoindexx{is optional attribute} \\
1545 \DWATlowerbound&0x22&\livelink{chap:classconstant}{constant},
1546         \livelink{chap:classexprloc}{exprloc},
1547         \livelink{chap:classreference}{reference}
1548             \addtoindexx{lower bound attribute}  \\
1549 \bbeb\textit{Reserved}&0x23&\textit{not applicable} \\
1550 \bbeb\textit{Reserved}&0x24&\textit{not applicable} \\
1551 \DWATproducer&0x25&\livelink{chap:classstring}{string}
1552             \addtoindexx{producer attribute}  \\
1553 \bbeb\textit{Reserved}&0x26&\textit{not applicable} \\
1554 \DWATprototyped&0x27&\livelink{chap:classflag}{flag}
1555             \addtoindexx{prototyped attribute}  \\
1556 \bbeb\textit{Reserved}&0x28&\textit{not applicable} \\
1557 \bbeb\textit{Reserved}&0x29&\textit{not applicable} \\
1558 \DWATreturnaddr&0x2a&\livelink{chap:classexprloc}{exprloc},
1559         \CLASSloclist
1560             \addtoindexx{return address attribute} \\
1561 \bbeb\textit{Reserved}&0x2b&\textit{not applicable} \\
1562 \DWATstartscope&0x2c&
1563         \livelink{chap:classconstant}{constant},
1564         \CLASSrnglist
1565             \addtoindexx{start scope attribute}  \\
1566 \bbeb\textit{Reserved}&0x2d&\textit{not applicable} \\
1567 \DWATbitstride&0x2e&\livelink{chap:classconstant}{constant},
1568         \livelink{chap:classexprloc}{exprloc},
1569         \livelink{chap:classreference}{reference}
1570             \addtoindexx{bit stride attribute}  \\
1571 \DWATupperbound&0x2f&\livelink{chap:classconstant}{constant},
1572         \livelink{chap:classexprloc}{exprloc},
1573         \livelink{chap:classreference}{reference}
1574             \addtoindexx{upper bound attribute}  \\
1575 \bbeb\textit{Reserved}&0x30&\textit{not applicable} \\
1576 \DWATabstractorigin&0x31&\livelink{chap:classreference}{reference}
1577             \addtoindexx{abstract origin attribute}  \\
1578 \DWATaccessibility&0x32&\livelink{chap:classconstant}{constant}
1579             \addtoindexx{accessibility attribute}  \\
1580 \DWATaddressclass&0x33&\livelink{chap:classconstant}{constant}
1581             \addtoindexx{address class attribute}  \\
1582 \DWATartificial&0x34&\livelink{chap:classflag}{flag}
1583             \addtoindexx{artificial attribute}  \\
1584 \DWATbasetypes&0x35&\livelink{chap:classreference}{reference}
1585             \addtoindexx{base types attribute}  \\
1586 \DWATcallingconvention&0x36&\livelink{chap:classconstant}{constant}
1587         \addtoindexx{calling convention attribute} \\
1588 \DWATcount&0x37&\livelink{chap:classconstant}{constant},
1589         \livelink{chap:classexprloc}{exprloc},
1590         \livelink{chap:classreference}{reference}
1591             \addtoindexx{count attribute}  \\
1592 \DWATdatamemberlocation&0x38&\livelink{chap:classconstant}{constant},
1593         \livelink{chap:classexprloc}{exprloc},
1594         \CLASSloclist
1595             \addtoindexx{data member attribute}  \\
1596 \DWATdeclcolumn&0x39&\livelink{chap:classconstant}{constant}
1597             \addtoindexx{declaration column attribute}  \\
1598 \DWATdeclfile&0x3a&\livelink{chap:classconstant}{constant}
1599             \addtoindexx{declaration file attribute}  \\
1600 \DWATdeclline&0x3b&\livelink{chap:classconstant}{constant}
1601             \addtoindexx{declaration line attribute}  \\
1602 \DWATdeclaration&0x3c&\livelink{chap:classflag}{flag}
1603             \addtoindexx{declaration attribute}  \\
1604 \DWATdiscrlist&0x3d&\livelink{chap:classblock}{block}
1605             \addtoindexx{discriminant list attribute}  \\
1606 \DWATencoding&0x3e&\livelink{chap:classconstant}{constant}
1607             \addtoindexx{encoding attribute}  \\
1608 \DWATexternal&\xiiif&\livelink{chap:classflag}{flag}
1609             \addtoindexx{external attribute}  \\
1610 \DWATframebase&0x40&\livelink{chap:classexprloc}{exprloc},
1611         \CLASSloclist
1612             \addtoindexx{frame base attribute}  \\
1613 \DWATfriend&0x41&\livelink{chap:classreference}{reference}
1614             \addtoindexx{friend attribute}  \\
1615 \DWATidentifiercase&0x42&\livelink{chap:classconstant}{constant}
1616             \addtoindexx{identifier case attribute}  \\
1617 \textit{Reserved}&0x43\footnote{Code 0x43 is reserved to allow backward compatible support of the
1618              DW\_AT\_macro\_info \mbox{attribute} which was
1619              defined in \DWARFVersionIV{} and earlier.}
1620             &\livelink{chap:classmacptr}{macptr}
1621             \addtoindexx{macro information attribute (legacy)!encoding}  \\
1622 \DWATnamelistitem&0x44&\livelink{chap:classreference}{reference}
1623             \addtoindexx{name list item attribute}  \\
1624 \DWATpriority&0x45&\livelink{chap:classreference}{reference}
1625             \addtoindexx{priority attribute}  \\
1626 \DWATsegment&0x46&\livelink{chap:classexprloc}{exprloc},
1627         \CLASSloclist
1628             \addtoindexx{segment attribute}  \\
1629 \DWATspecification&0x47&\livelink{chap:classreference}{reference}
1630         \addtoindexx{specification attribute}  \\
1631 \DWATstaticlink&0x48&\livelink{chap:classexprloc}{exprloc},
1632         \CLASSloclist
1633             \addtoindexx{static link attribute}  \\
1634 \DWATtype&0x49&\livelink{chap:classreference}{reference}
1635             \addtoindexx{type attribute}  \\
1636 \DWATuselocation&0x4a&\livelink{chap:classexprloc}{exprloc},
1637         \CLASSloclist
1638             \addtoindexx{location list attribute}  \\
1639 \DWATvariableparameter&0x4b&\livelink{chap:classflag}{flag}
1640             \addtoindexx{variable parameter attribute}  \\
1641 \DWATvirtuality&0x4c&\livelink{chap:classconstant}{constant}
1642             \addtoindexx{virtuality attribute}  \\
1643 \DWATvtableelemlocation&0x4d&\livelink{chap:classexprloc}{exprloc},
1644         \CLASSloclist
1645             \addtoindexx{vtable element location attribute}  \\
1646 \DWATallocated&0x4e&\livelink{chap:classconstant}{constant},
1647         \livelink{chap:classexprloc}{exprloc},
1648         \livelink{chap:classreference}{reference}
1649             \addtoindexx{allocated attribute}  \\
1650 \DWATassociated&0x4f&\livelink{chap:classconstant}{constant},
1651         \livelink{chap:classexprloc}{exprloc},
1652         \livelink{chap:classreference}{reference}
1653             \addtoindexx{associated attribute}  \\
1654 \DWATdatalocation&0x50&\livelink{chap:classexprloc}{exprloc}
1655         \addtoindexx{data location attribute}  \\
1656 \DWATbytestride&0x51&\livelink{chap:classconstant}{constant},
1657         \livelink{chap:classexprloc}{exprloc},
1658         \livelink{chap:classreference}{reference}
1659             \addtoindexx{byte stride attribute}  \\
1660 \DWATentrypc&0x52&\livelink{chap:classaddress}{address},
1661         \livelink{chap:classconstant}{constant}
1662             \addtoindexx{entry PC attribute}  \\
1663 \DWATuseUTFeight&0x53&\livelink{chap:classflag}{flag}
1664             \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8}  \\
1665 \DWATextension&0x54&\livelink{chap:classreference}{reference}
1666             \addtoindexx{extension attribute}  \\
1667 \DWATranges&0x55&
1668         \CLASSrnglist
1669             \addtoindexx{ranges attribute}  \\
1670 \DWATtrampoline&0x56&\livelink{chap:classaddress}{address},
1671         \livelink{chap:classflag}{flag},
1672         \livelink{chap:classreference}{reference},
1673         \livelink{chap:classstring}{string}
1674             \addtoindexx{trampoline attribute}  \\
1675 \DWATcallcolumn&0x57&\livelink{chap:classconstant}{constant}
1676             \addtoindexx{call column attribute}  \\
1677 \DWATcallfile&0x58&\livelink{chap:classconstant}{constant}
1678             \addtoindexx{call file attribute}  \\
1679 \DWATcallline&0x59&\livelink{chap:classconstant}{constant}
1680             \addtoindexx{call line attribute}  \\
1681 \DWATdescription&0x5a&\livelink{chap:classstring}{string}
1682             \addtoindexx{description attribute}  \\
1683 \DWATbinaryscale&0x5b&\livelink{chap:classconstant}{constant}
1684             \addtoindexx{binary scale attribute}  \\
1685 \DWATdecimalscale&0x5c&\livelink{chap:classconstant}{constant}
1686             \addtoindexx{decimal scale attribute}  \\
1687 \DWATsmall{} &0x5d&\livelink{chap:classreference}{reference}
1688             \addtoindexx{small attribute}  \\
1689 \DWATdecimalsign&0x5e&\livelink{chap:classconstant}{constant}
1690             \addtoindexx{decimal scale attribute}  \\
1691 \DWATdigitcount&0x5f&\livelink{chap:classconstant}{constant}
1692             \addtoindexx{digit count attribute}  \\
1693 \DWATpicturestring&0x60&\livelink{chap:classstring}{string}
1694             \addtoindexx{picture string attribute}  \\
1695 \DWATmutable&0x61&\livelink{chap:classflag}{flag}
1696             \addtoindexx{mutable attribute}  \\
1697 \DWATthreadsscaled&0x62&\livelink{chap:classflag}{flag}
1698             \addtoindexx{thread scaled attribute}  \\
1699 \DWATexplicit&0x63&\livelink{chap:classflag}{flag}
1700             \addtoindexx{explicit attribute}  \\
1701 \DWATobjectpointer&0x64&\livelink{chap:classreference}{reference}
1702             \addtoindexx{object pointer attribute}  \\
1703 \DWATendianity&0x65&\livelink{chap:classconstant}{constant}
1704             \addtoindexx{endianity attribute}  \\
1705 \DWATelemental&0x66&\livelink{chap:classflag}{flag}
1706             \addtoindexx{elemental attribute}  \\
1707 \DWATpure&0x67&\livelink{chap:classflag}{flag}
1708             \addtoindexx{pure attribute}  \\
1709 \DWATrecursive&0x68&\livelink{chap:classflag}{flag}
1710             \addtoindexx{recursive attribute}  \\
1711 \DWATsignature{} &0x69&\livelink{chap:classreference}{reference}
1712             \addtoindexx{signature attribute}  \\
1713 \DWATmainsubprogram{} &0x6a&\livelink{chap:classflag}{flag}
1714             \addtoindexx{main subprogram attribute}  \\
1715 \DWATdatabitoffset{} &0x6b&\livelink{chap:classconstant}{constant}
1716             \addtoindexx{data bit offset attribute}  \\
1717 \DWATconstexpr{} &0x6c&\livelink{chap:classflag}{flag}
1718             \addtoindexx{constant expression attribute}  \\
1719 \DWATenumclass{} &0x6d&\livelink{chap:classflag}{flag}
1720             \addtoindexx{enumeration class attribute}  \\
1721 \DWATlinkagename{} &0x6e&\livelink{chap:classstring}{string}
1722             \addtoindexx{linkage name attribute}  \\
1723 \DWATstringlengthbitsize{}~\ddag&0x6f&
1724                 \livelink{chap:classconstant}{constant}
1725             \addtoindexx{string length attribute!size of length}  \\
1726 \DWATstringlengthbytesize{}~\ddag&0x70&
1727                 \livelink{chap:classconstant}{constant}
1728             \addtoindexx{string length attribute!size of length}  \\
1729 \DWATrank~\ddag&0x71&
1730         \livelink{chap:classconstant}{constant},
1731         \livelink{chap:classexprloc}{exprloc}
1732             \addtoindexx{rank attribute}  \\
1733 \DWATstroffsetsbase~\ddag&0x72&
1734                 \livelinki{chap:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class}
1735             \addtoindexx{string offsets base!encoding}  \\
1736 \DWATaddrbase~\ddag &0x73&
1737                 \livelinki{chap:classaddrptr}{addrptr}{addrptr class}
1738             \addtoindexx{address table base!encoding} \\
1739 \DWATrnglistsbase~\ddag&0x74&
1740                 \CLASSrnglistsptr
1741             \addtoindexx{range list base!encoding} \\
1742 \textit{Reserved} &0x75& \textit{Unused} \\
1743 \DWATdwoname~\ddag &0x76&
1744                 \livelink{chap:classstring}{string}
1745             \addtoindexx{split DWARF object file name!encoding} \\
1746 \DWATreference~\ddag &0x77&
1747         \livelink{chap:classflag}{flag} \\
1748 \DWATrvaluereference~\ddag &0x78&
1749         \livelink{chap:classflag}{flag} \\
1750 \DWATmacros~\ddag &0x79&\livelink{chap:classmacptr}{macptr}
1751         \addtoindexx{macro information attribute}  \\
1752 \DWATcallallcalls~\ddag &0x7a&\CLASSflag
1753         \addtoindexx{all calls summary attribute} \\
1754 \DWATcallallsourcecalls~\ddag &0x7b &\CLASSflag
1755         \addtoindexx{all source calls summary attribute} \\
1756 \DWATcallalltailcalls~\ddag &0x7c&\CLASSflag
1757         \addtoindexx{all tail calls summary attribute} \\
1758 \DWATcallreturnpc~\ddag &0x7d &\CLASSaddress
1759         \addtoindexx{call return PC attribute} \\
1760 \DWATcallvalue~\ddag &0x7e &\CLASSexprloc
1761         \addtoindexx{call value attribute} \\
1762 \DWATcallorigin~\ddag &0x7f &\CLASSexprloc
1763         \addtoindexx{call origin attribute} \\
1764 \DWATcallparameter~\ddag &0x80 &\CLASSreference
1765         \addtoindexx{call parameter attribute} \\
1766 \DWATcallpc~\ddag &0x81 &\CLASSaddress
1767         \addtoindexx{call PC attribute} \\
1768 \DWATcalltailcall~\ddag &0x82 &\CLASSflag
1769         \addtoindexx{call tail call attribute} \\
1770 \DWATcalltarget~\ddag &0x83 &\CLASSexprloc
1771         \addtoindexx{call target attribute} \\
1772 \DWATcalltargetclobbered~\ddag &0x84 &\CLASSexprloc
1773         \addtoindexx{call target clobbered attribute} \\
1774 \DWATcalldatalocation~\ddag &0x85 &\CLASSexprloc
1775         \addtoindexx{call data location attribute} \\
1776 \DWATcalldatavalue~\ddag &0x86 &\CLASSexprloc
1777         \addtoindexx{call data value attribute} \\
1778 \DWATnoreturn~\ddag &0x87 &\CLASSflag
1779         \addtoindexx{noreturn attribute} \\
1780 \DWATalignment~\ddag &0x88 &\CLASSconstant
1781         \addtoindexx{alignment attribute} \\
1782 \DWATexportsymbols~\ddag &0x89 &\CLASSflag
1783         \addtoindexx{export symbols attribute} \\
1784 \DWATdeleted~\ddag &0x8a &\CLASSflag \addtoindexx{deleted attribute} \\
1785 \DWATdefaulted~\ddag &0x8b &\CLASSconstant \addtoindexx{defaulted attribute} \\
1786 \DWATloclistsbase~\ddag &0x8c &\CLASSloclistsptr \addtoindexx{location list base attribute} \\
1787 \DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding}  \\
1788 \DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding}  \\
1789
1790 \end{longtable}
1791 \end{centering}
1792
1793 \subsection{Classes and Forms}
1794 \label{datarep:classesandforms}
1795 Each class is a set of forms which have related representations
1796 and which are given a common interpretation according to the
1797 attribute in which the form is used.
1798 The attribute form governs how the value of an attribute is
1799 encoded.
1800 The classes and the forms they include are listed below.
1801
1802 Form \DWFORMsecoffsetTARG{}
1803 is a member of more than one class, namely
1804 \CLASSaddrptr,
1805 \CLASSlineptr,
1806 \CLASSloclist, \CLASSloclistsptr,
1807 \CLASSmacptr,
1808 \CLASSrnglist{}, \CLASSrnglistsptr,
1809 and
1810 \CLASSstroffsetsptr;
1811 as a result, it is not possible for an
1812 attribute to allow more than one of these classes.
1813 The list of classes allowed by the applicable attribute in
1814 Table \refersec{tab:attributeencodings}
1815 determines the class of the form.
1816
1817 \needlines{4}
1818 In the form descriptions that follow, some forms are said
1819 to depend in part on the value of an attribute of the
1820 \definition{\associatedcompilationunit}:
1821 \begin{itemize}
1822 \item
1823 In the case of a \splitDWARFobjectfile{}, the associated
1824 compilation unit is the skeleton compilation unit corresponding
1825 to the containing unit.
1826 \item Otherwise, the associated compilation unit
1827 is the containing unit.
1828 \end{itemize}
1829
1830 \needlines{4}
1831 Each possible form belongs to one or more of the following classes
1832 (see Table \refersec{tab:classesofattributevalue} for a summary of
1833 the purpose and general usage of each class):
1834
1835 \begin{itemize}
1836
1837 \item \CLASSaddress \\
1838 \livetarg{datarep:classaddress}{}
1839 Represented as either:
1840 \begin{itemize}
1841 \item An object of appropriate size to hold an
1842 address on the target machine (\DWFORMaddrTARG).
1843 The size is encoded in the compilation unit header
1844 (see Section \refersec{datarep:compilationunitheader}).
1845 This address is relocatable in a relocatable object file and
1846 is relocated in an executable file or shared object file.
1847
1848 \item An indirect index into a table of addresses (as
1849 described in the previous bullet) in the
1850 \dotdebugaddr{} section (\DWFORMaddrxTARG).
1851 The representation of a \DWFORMaddrxNAME{} value is an unsigned
1852 \addtoindex{LEB128} value, which is interpreted as a zero-based
1853 index into an array of addresses in the \dotdebugaddr{} section.
1854 The index is relative to the value of the \DWATaddrbase{} attribute
1855 of the associated compilation unit.
1856
1857 \end{itemize}
1858
1859 \needlines{5}
1860 \item \CLASSaddrptr \\
1861 \livetarg{datarep:classaddrptr}{}
1862 This is an offset into the \dotdebugaddr{} section (\DWFORMsecoffset). It
1863 consists of an offset from the beginning of the \dotdebugaddr{} section to the
1864 beginning of the list of machine addresses information for the
1865 referencing entity. It is relocatable in
1866 a relocatable object file, and relocated in an executable or
1867 shared object file. In the \thirtytwobitdwarfformat, this offset
1868 is a 4-byte unsigned value; in the 64-bit DWARF
1869 format, it is an 8-byte unsigned value (see Section
1870 \refersec{datarep:32bitand64bitdwarfformats}).
1871
1872 \textit{This class is new in \DWARFVersionV.}
1873
1874 \needlines{4}
1875 \item \CLASSblock \\
1876 \livetarg{datarep:classblock}{}
1877 Blocks come in four forms:
1878 \begin{itemize}
1879 \item
1880 A 1-byte length followed by 0 to 255 contiguous information
1881 bytes (\DWFORMblockoneTARG).
1882
1883 \item
1884 A 2-byte length followed by 0 to 65,535 contiguous information
1885 bytes (\DWFORMblocktwoTARG).
1886
1887 \item
1888 A 4-byte length followed by 0 to 4,294,967,295 contiguous
1889 information bytes (\DWFORMblockfourTARG).
1890
1891 \item
1892 An unsigned LEB128\addtoindexx{LEB128!unsigned}
1893 length followed by the number of bytes
1894 specified by the length (\DWFORMblockTARG).
1895 \end{itemize}
1896
1897 In all forms, the length is the number of information bytes
1898 that follow. The information bytes may contain any mixture
1899 of relocated (or relocatable) addresses, references to other
1900 debugging information entries or data bytes.
1901
1902 \item \CLASSconstant \\
1903 \livetarg{datarep:classconstant}{}
1904 There are eight forms of constants. There are fixed length
1905 constant data forms for one-, two-, four-, eight- and sixteen-byte values
1906 (respectively,
1907 \DWFORMdataoneTARG,
1908 \DWFORMdatatwoTARG,
1909 \DWFORMdatafourTARG,
1910 \DWFORMdataeightTARG{} and
1911 \DWFORMdatasixteenTARG).
1912 There are variable length constant
1913 data forms encoded using
1914 signed LEB128 numbers (\DWFORMsdataTARG) and unsigned
1915 LEB128 numbers (\DWFORMudataTARG).
1916 There is also an implicit constant (\DWFORMimplicitconst),
1917 whose value is provided as part of the abbreviation
1918 declaration.
1919
1920 \needlines{4}
1921 The data in \DWFORMdataone,
1922 \DWFORMdatatwo,
1923 \DWFORMdatafour{},
1924 \DWFORMdataeight{} and
1925 \DWFORMdatasixteen{}
1926 can be anything. Depending on context, it may
1927 be a signed integer, an unsigned integer, a floating\dash point
1928 constant, or anything else. A consumer must use context to
1929 know how to interpret the bits, which if they are target
1930 machine data (such as an integer or floating-point constant)
1931 will be in target machine \byteorder.
1932
1933 \textit{If one of the \DWFORMdataTARG\textless n\textgreater
1934 forms is used to represent a
1935 signed or unsigned integer, it can be hard for a consumer
1936 to discover the context necessary to determine which
1937 interpretation is intended. Producers are therefore strongly
1938 encouraged to use \DWFORMsdata{} or
1939 \DWFORMudata{} for signed and
1940 unsigned integers respectively, rather than
1941 \DWFORMdata\textless n\textgreater.}
1942
1943 \needlines{4}
1944 \item \CLASSexprloc \\
1945 \livetarg{datarep:classexprloc}{}
1946 This is an unsigned LEB128\addtoindexx{LEB128!unsigned} length
1947 followed by the number of information bytes specified by the
1948 length (\DWFORMexprlocTARG).
1949 The information bytes contain a DWARF expression
1950 (see Section \refersec{chap:dwarfexpressions})
1951 or location description
1952 (see Section \refersec{chap:locationdescriptions}).
1953
1954 \needlines{4}
1955 \item \CLASSflag \\
1956 \livetarg{datarep:classflag}{}
1957 A flag \addtoindexx{flag class}
1958 is represented explicitly as a single byte of data
1959 (\DWFORMflagTARG) or implicitly (\DWFORMflagpresentTARG). In the
1960 first case, if the \nolink{flag} has value zero, it indicates the
1961 absence of the attribute; if the \nolink{flag} has a non-zero value,
1962 it indicates the presence of the attribute. In the second
1963 case, the attribute is implicitly indicated as present, and
1964 no value is encoded in the debugging information entry itself.
1965
1966 \needlines{4}
1967 \item \CLASSlineptr \\
1968 \livetarg{datarep:classlineptr}{}
1969 This is an offset into
1970 \addtoindexx{section offset!in class lineptr value}
1971 the
1972 \dotdebugline{} or \dotdebuglinedwo{} section
1973 (\DWFORMsecoffset).
1974 It consists of an offset from the beginning of the
1975 \dotdebugline{}
1976 section to the first byte of
1977 the data making up the line number list for the compilation
1978 unit.
1979 It is relocatable in a relocatable object file, and
1980 relocated in an executable or shared object file. In the
1981 \thirtytwobitdwarfformat, this offset is a 4-byte unsigned value;
1982 in the \sixtyfourbitdwarfformat, it is an 8-byte unsigned value
1983 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1984
1985 \needlines{10}
1986 \item \CLASSloclist \\
1987 \livetarg{datarep:classloclist}{}
1988 This is represented as either:
1989 \begin{itemize}
1990 \item
1991 An index into the \dotdebugloclists{} section (\DWFORMloclistxTARG).
1992 The unsigned ULEB operand identifies an offset location
1993 relative to the base of that section (the location of the first offset
1994 in the section, not the first byte of the section). The contents of
1995 that location is then added to the base to determine the location of
1996 the target list of entries.
1997 \item
1998 An offset into the \dotdebugloclists{} section (\DWFORMsecoffset).
1999 The operand consists of a byte
2000 offset\addtoindexx{section offset!in class loclist value}
2001 from the beginning of the \dotdebugloclists{} section.
2002 It is relocatable in a relocatable object file, and
2003 relocated in an executable or shared object file. In the
2004 \thirtytwobitdwarfformat, this offset is a 4-byte unsigned value;
2005 in the \sixtyfourbitdwarfformat, it is an 8-byte unsigned value
2006 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2007 \end{itemize}
2008
2009 \textit{This class is new in \DWARFVersionV.}
2010
2011 \item \CLASSloclistsptr \\
2012 \livetarg{datarep:classloclistsptr}{}
2013 This is an offset into the \dotdebugloclists{} section (\DWFORMsecoffset).
2014 The operand consists of a byte
2015 offset\addtoindexx{section offset!in class loclistsptr}
2016 from the beginning of the \dotdebugloclists{} section.
2017 It is relocatable in a relocatable object file, and
2018 relocated in an executable or shared object file. In the
2019 \thirtytwobitdwarfformat, this offset is a 4-byte unsigned value;
2020 in the \sixtyfourbitdwarfformat, it is an 8-byte unsigned value
2021 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2022
2023 \textit{This class is new in \DWARFVersionV.}
2024
2025 \item \CLASSmacptr \\
2026 \livetarg{datarep:classmacptr}{}
2027 This is an
2028 \addtoindexx{section offset!in class macptr value}
2029 offset into the
2030 \dotdebugmacro{} or \dotdebugmacrodwo{} section
2031 (\DWFORMsecoffset).
2032 It consists of an offset from the beginning of the
2033 \dotdebugmacro{} or \dotdebugmacrodwo{}
2034 section to the the header making up the
2035 macro information list for the compilation unit.
2036 It is relocatable in a relocatable object file, and
2037 relocated in an executable or shared object file. In the
2038 \thirtytwobitdwarfformat, this offset is a 4-byte unsigned value;
2039 in the \sixtyfourbitdwarfformat, it is an 8-byte unsigned value
2040 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2041
2042 \needlines{8}
2043 \item \CLASSrnglist \\
2044 \livetarg{datarep:classrnglist}{}
2045 This is represented as either:
2046 \begin{itemize}
2047 \item
2048 An index into the \dotdebugrnglists{} section (\DWFORMrnglistxTARG).
2049 The unsigned ULEB operand identifies an offset location
2050 relative to the base of that section (the location of the first offset
2051 in the section, not the first byte of the section). The contents of
2052 that location is then added to the base to determine the location of
2053 the target range list of entries.
2054 \item
2055 \bb
2056 An offset into the \dotdebugrnglists{} section (\DWFORMsecoffset).
2057 The operand consists of a byte
2058 offset\addtoindexx{section offset!in class rnglist value}
2059 \eb
2060 from the beginning of the \dotdebugrnglists{} section.
2061 It is relocatable in a relocatable object file, and
2062 relocated in an executable or shared object file. In the
2063 \thirtytwobitdwarfformat, this offset is a 4-byte unsigned value;
2064 in the \sixtyfourbitdwarfformat, it is an 8-byte unsigned value
2065 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2066 \end{itemize}
2067
2068 \textit{This class is new in \DWARFVersionV.}
2069
2070 \needlines{4}
2071 \item \CLASSrnglistsptr \\
2072 \livetarg{datarep:classrnglistsptr}{}
2073 This is an offset\addtoindexx{section offset!in class rnglistsptr}
2074 into the \dotdebugrnglists{} section (\DWFORMsecoffset).
2075 It consists of a byte offset from the beginning of the
2076 \dotdebugrnglists{} section.
2077 It is relocatable in a relocatable object file, and relocated
2078 in an executable or shared object file.
2079 In the \thirtytwobitdwarfformat, this offset
2080 is a 4-byte unsigned value; in the 64-bit DWARF
2081 format, it is an 8-byte unsigned value (see Section
2082 \refersec{datarep:32bitand64bitdwarfformats}).
2083
2084 \textit{This class is new in \DWARFVersionV.}
2085
2086 \needlines{4}
2087 \item \CLASSreference \\
2088 \livetarg{datarep:classreference}{}
2089 There are four types of reference.\addtoindexx{reference class}
2090 \begin{itemize}
2091 \item
2092 The first type of reference can identify any debugging
2093 information entry within the containing unit.
2094 This type of reference is an
2095 offset\addtoindexx{section offset!in class reference value}
2096 from the first byte of the compilation
2097 header for the compilation unit containing the reference. There
2098 are five forms for this type of reference. There are fixed
2099 length forms for one, two, four and eight byte offsets
2100 (respectively,
2101 \DWFORMrefnMARK
2102 \DWFORMrefoneTARG,
2103 \DWFORMreftwoTARG,
2104 \DWFORMreffourTARG,
2105 and \DWFORMrefeightTARG).
2106 There is also an unsigned variable
2107 length offset encoded form that uses
2108 unsigned LEB128\addtoindexx{LEB128!unsigned} numbers
2109 (\DWFORMrefudataTARG).
2110 Because this type of reference is within
2111 the containing compilation unit no relocation of the value
2112 is required.
2113
2114 \item
2115 The second type of reference can identify any debugging
2116 information entry within a
2117 \dotdebuginfo{} section; in particular,
2118 it may refer to an entry in a different compilation unit
2119 from the unit containing the reference, and may refer to an
2120 entry in a different shared object file.  This type of reference
2121 (\DWFORMrefaddrTARG)
2122 is an offset from the beginning of the
2123 \dotdebuginfo{}
2124 section of the target executable or shared object file, or, for
2125 references within a \addtoindex{supplementary object file},
2126 an offset from the beginning of the local \dotdebuginfo{} section;
2127 it is relocatable in a relocatable object file and frequently
2128 relocated in an executable or shared object file. For
2129 references from one shared object or static executable file
2130 to another, the relocation and identification of the target
2131 object must be performed by the consumer. In the
2132 \thirtytwobitdwarfformat, this offset is a 4-byte unsigned value;
2133 in the \sixtyfourbitdwarfformat, it is an 8-byte
2134 unsigned value
2135 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2136
2137 \textit{A debugging information entry that may be referenced by
2138 another compilation unit using
2139 \DWFORMrefaddr{} must have a global symbolic name.}
2140
2141 \textit{For a reference from one executable or shared object file to
2142 another, the reference is resolved by the debugger to identify
2143 the executable or shared object file and the offset into that
2144 file\textquoteright s \dotdebuginfo{}
2145 section in the same fashion as the run
2146 time loader, either when the debug information is first read,
2147 or when the reference is used.}
2148
2149 \item
2150 The third type of reference can identify any debugging
2151 information type entry that has been placed in its own
2152 \addtoindex{type unit}. This type of
2153 reference (\DWFORMrefsigeightTARG) is the
2154 \addtoindexx{type signature}
2155 8-byte type signature
2156 (see Section \refersec{datarep:typesignaturecomputation})
2157 that was computed for the type.
2158
2159 \item
2160 The fourth type of reference is a reference from within the
2161 \dotdebuginfo{} section of the executable or shared object file to
2162 a debugging information entry in the \dotdebuginfo{} section of
2163 a \addtoindex{supplementary object file}.
2164 This type of reference (\DWFORMrefsupfourTARG{}
2165 \bb
2166 or \DWFORMrefsupeightTARG{}) is a 4- or 8-byte offset (respectively)
2167 \eb
2168 from the beginning of the \dotdebuginfo{} section in the
2169 \addtoindex{supplementary object file}.
2170
2171 \textit{The use of compilation unit relative references will reduce the
2172 number of link\dash time relocations and so speed up linking. The
2173 use of the second, third and fourth type of reference allows for the
2174 sharing of information, such as types, across compilation
2175 units, while the fourth type further allows for sharing of information
2176 across compilation units from different executables or shared object files.}
2177
2178 \textit{A reference to any kind of compilation unit identifies the
2179 debugging information entry for that unit, not the preceding
2180 header.}
2181 \end{itemize}
2182
2183 \needlines{4}
2184 \item \CLASSstring \\
2185 \livetarg{datarep:classstring}{}
2186 A string is a sequence of contiguous non\dash null bytes followed by
2187 one null byte.
2188 \addtoindexx{string class}
2189 A string may be represented:
2190 \begin{itemize}
2191 \setlength{\itemsep}{0em}
2192 \item immediately in the debugging information entry itself
2193 (\DWFORMstringTARG),
2194
2195 \item as an
2196 \addtoindexx{section offset!in class string value}
2197 offset into a string table contained in
2198 the \dotdebugstr{} section of the object file (\DWFORMstrpTARG),
2199 the \dotdebuglinestr{} section of the object file (\DWFORMlinestrpTARG),
2200 or as an offset into a string table contained in the
2201 \dotdebugstr{} section of a \addtoindex{supplementary object file}
2202 (\DWFORMstrpsupTARG).  \DWFORMstrpsupNAME{} offsets from the \dotdebuginfo{}
2203 section of a \addtoindex{supplementary object file}
2204 refer to the local \dotdebugstr{} section of that same file.
2205 In the \thirtytwobitdwarfformat, the representation of a
2206 \DWFORMstrpNAME{},
2207 \bb
2208 \DWFORMlinestrpNAME{}
2209 \eb
2210 or \DWFORMstrpsupNAME{}
2211 value is a 4-byte unsigned offset; in the \sixtyfourbitdwarfformat,
2212 it is an 8-byte unsigned offset
2213 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2214
2215 \needlines{6}
2216 \item as an indirect offset into the string table using an
2217 index into a table of offsets contained in the
2218 \dotdebugstroffsets{} section of the object file
2219 \bb
2220 (\DWFORMstrxTARG, \DWFORMstrxoneTARG, \DWFORMstrxtwoTARG, \DWFORMstrxthreeTARG{} and \DWFORMstrxfourTARG).
2221 \eb
2222 The representation of a \DWFORMstrxNAME{} value is an unsigned
2223 \addtoindex{LEB128} value, which is interpreted as a zero-based
2224 index into an array of offsets in the \dotdebugstroffsets{} section.
2225 \bb
2226 The representation of a \DWFORMstrxoneNAME, \DWFORMstrxtwoNAME,
2227 \DWFORMstrxthreeNAME{} or \DWFORMstrxfourNAME{} value is a
2228 1-, 2-, 3- or 4-byte unsigned integer value, respectively,
2229 which is similarly interpretated.
2230 \eb
2231 The offset entries in the \dotdebugstroffsets{} section have the
2232 same representation as \DWFORMstrp{} values.
2233 \end{itemize}
2234 Any combination of these three forms may be used within a single compilation.
2235
2236 If the \DWATuseUTFeight{}
2237 \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} attribute is specified for the
2238 compilation, partial, skeleton or type unit entry, string values are encoded using the
2239 UTF\dash 8 (\addtoindex{Unicode} Transformation Format\dash 8) from the Universal
2240 Character Set standard (ISO/IEC 10646\dash 1:1993).
2241 \addtoindexx{ISO 10646 character set standard}
2242 Otherwise, the string representation is unspecified.
2243
2244 \textit{The \addtoindex{Unicode} Standard Version 3 is fully compatible with
2245 ISO/IEC 10646\dash 1:1993.
2246 \addtoindexx{ISO 10646 character set standard}
2247 It contains all the same characters
2248 and encoding points as ISO/IEC 10646, as well as additional
2249 information about the characters and their use.}
2250
2251 \needlines{4}
2252 \textit{Earlier versions of DWARF did not specify the representation
2253 of strings; for compatibility, this version also does
2254 not. However, the UTF\dash 8 representation is strongly recommended.}
2255
2256 \needlines{4}
2257 \item \CLASSstroffsetsptr \\
2258 \livetarg{datarep:classstroffsetsptr}{}
2259 This is an offset into the \dotdebugstroffsets{} section
2260 (\DWFORMsecoffset). It consists of an offset from the beginning of the
2261 \dotdebugstroffsets{} section to the
2262 beginning of the string offsets information for the
2263 referencing entity. It is relocatable in
2264 a relocatable object file, and relocated in an executable or
2265 shared object file. In the \thirtytwobitdwarfformat, this offset
2266 is a 4-byte unsigned value; in the \sixtyfourbitdwarfformat,
2267 it is an 8-byte unsigned value (see Section
2268 \refersec{datarep:32bitand64bitdwarfformats}).
2269
2270 \textit{This class is new in \DWARFVersionV.}
2271
2272 \end{itemize}
2273
2274 In no case does an attribute use one of the classes
2275 \CLASSaddrptr,
2276 \CLASSlineptr,
2277 \CLASSloclistsptr,
2278 \CLASSmacptr,
2279 \CLASSrnglistsptr{} or
2280 \CLASSstroffsetsptr{}
2281 to point into either the
2282 \dotdebuginfo{} or \dotdebugstr{} section.
2283
2284 \subsection{Form Encodings}
2285 \label{datarep:formencodings}
2286 The form encodings are listed in
2287 Table \referfol{tab:attributeformencodings}.
2288
2289 \needlines{8}
2290 \begin{centering}
2291 \setlength{\extrarowheight}{0.1cm}
2292 \begin{longtable}{l|c|l}
2293   \caption{Attribute form encodings} \label{tab:attributeformencodings} \\
2294   \hline \bfseries Form name&\bfseries Value &\bfseries Classes \\ \hline
2295 \endfirsthead
2296   \bfseries Form name&\bfseries Value &\bfseries Classes\\ \hline
2297 \endhead
2298   \hline \emph{Continued on next page}
2299 \endfoot
2300   \hline \ddag\ \textit{New in DWARF Version 5}
2301 \endlastfoot
2302
2303 \DWFORMaddr &0x01&\livelink{chap:classaddress}{address}  \\
2304 \textit{Reserved} &0x02& \\
2305 \DWFORMblocktwo &0x03&\livelink{chap:classblock}{block} \\
2306 \DWFORMblockfour &0x04&\livelink{chap:classblock}{block}  \\
2307 \DWFORMdatatwo &0x05&\livelink{chap:classconstant}{constant} \\
2308 \DWFORMdatafour &0x06&\livelink{chap:classconstant}{constant} \\
2309 \DWFORMdataeight &0x07&\livelink{chap:classconstant}{constant} \\
2310 \DWFORMstring&0x08&\livelink{chap:classstring}{string} \\
2311 \DWFORMblock&0x09&\livelink{chap:classblock}{block} \\
2312 \DWFORMblockone &0x0a&\livelink{chap:classblock}{block} \\
2313 \DWFORMdataone &0x0b&\livelink{chap:classconstant}{constant} \\
2314 \DWFORMflag&0x0c&\livelink{chap:classflag}{flag} \\
2315 \DWFORMsdata&0x0d&\livelink{chap:classconstant}{constant}    \\
2316 \DWFORMstrp&0x0e&\livelink{chap:classstring}{string}         \\
2317 \DWFORMudata&0x0f&\livelink{chap:classconstant}{constant}         \\
2318 \DWFORMrefaddr&0x10&\livelink{chap:classreference}{reference}         \\
2319 \DWFORMrefone&0x11&\livelink{chap:classreference}{reference}          \\
2320 \DWFORMreftwo&0x12&\livelink{chap:classreference}{reference}         \\
2321 \DWFORMreffour&0x13&\livelink{chap:classreference}{reference}         \\
2322 \DWFORMrefeight&0x14&\livelink{chap:classreference}{reference} \\
2323 \DWFORMrefudata&0x15&\livelink{chap:classreference}{reference}  \\
2324 \DWFORMindirect&0x16&(see Section \refersec{datarep:abbreviationstables}) \\
2325 \DWFORMsecoffset{} &0x17& \CLASSaddrptr, \CLASSlineptr, \CLASSloclist, \CLASSloclistsptr, \\
2326                    &    & \CLASSmacptr, \CLASSrnglist, \CLASSrnglistsptr, \CLASSstroffsetsptr \\
2327 \DWFORMexprloc{} &0x18&\livelink{chap:classexprloc}{exprloc} \\
2328 \DWFORMflagpresent{} &0x19&\livelink{chap:classflag}{flag} \\
2329 \DWFORMstrx{} \ddag &0x1a&\livelink{chap:classstring}{string} \\
2330 \DWFORMaddrx{} \ddag &0x1b&\livelink{chap:classaddress}{address} \\
2331 \DWFORMrefsupfour{}~\ddag &0x1c &\livelink{chap:classreference}{reference} \\
2332 \DWFORMstrpsup{}~\ddag &0x1d &\livelink{chap:classstring}{string} \\
2333 \DWFORMdatasixteen~\ddag &0x1e &\CLASSconstant \\
2334 \DWFORMlinestrp~\ddag &0x1f &\CLASSstring \\
2335 \DWFORMrefsigeight &0x20 &\livelink{chap:classreference}{reference} \\
2336 \DWFORMimplicitconst~\ddag &0x21 &\CLASSconstant \\
2337 \DWFORMloclistx~\ddag &0x22 &\CLASSloclist \\
2338 \DWFORMrnglistx~\ddag &0x23 &\CLASSrnglist \\
2339 \DWFORMrefsupeight{}~\ddag &0x24 &\CLASSreference \\
2340 \bb
2341 \DWFORMstrxone{}~\ddag   &0x25 &\CLASSstring \\
2342 \DWFORMstrxtwo{}~\ddag   &0x26 &\CLASSstring \\
2343 \DWFORMstrxthree{}~\ddag &0x27 &\CLASSstring \\
2344 \eb
2345 \DWFORMstrxfour{}~\ddag  &0x28 &\CLASSstring \\
2346 \end{longtable}
2347 \end{centering}
2348
2349
2350 \needlines{6}
2351 \section{Variable Length Data}
2352 \label{datarep:variablelengthdata}
2353 \addtoindexx{variable length data|see {LEB128}}
2354 Integers may be
2355 \addtoindexx{Little-Endian Base 128|see{LEB128}}
2356 encoded using \doublequote{Little-Endian Base 128}
2357 \addtoindexx{little-endian encoding|see{endian attribute}}
2358 (LEB128) numbers.
2359 \addtoindexx{LEB128}
2360 LEB128 is a scheme for encoding integers
2361 densely that exploits the assumption that most integers are
2362 small in magnitude.
2363
2364 \textit{This encoding is equally suitable whether the target machine
2365 architecture represents data in big-endian or little-endian
2366 \byteorder. It is \doublequote{little-endian} only in the sense that it
2367 avoids using space to represent the \doublequote{big} end of an
2368 unsigned integer, when the big end is all zeroes or sign
2369 extension bits.}
2370
2371 Unsigned LEB128\addtoindexx{LEB128!unsigned} (\addtoindex{ULEB128})
2372 numbers are encoded as follows:
2373 \addtoindexx{LEB128!unsigned, encoding as}
2374 start at the low order end of an unsigned integer and chop
2375 it into 7-bit chunks. Place each chunk into the low order 7
2376 bits of a byte. Typically, several of the high order bytes
2377 will be zero; discard them. Emit the remaining bytes in a
2378 stream, starting with the low order byte; set the high order
2379 bit on each byte except the last emitted byte. The high bit
2380 of zero on the last byte indicates to the decoder that it
2381 has encountered the last byte.
2382
2383 The integer zero is a special case, consisting of a single
2384 zero byte.
2385
2386 Table \refersec{tab:examplesofunsignedleb128encodings}
2387 gives some examples of unsigned LEB128\addtoindexx{LEB128!unsigned}
2388 numbers. The
2389 0x80 in each case is the high order bit of the byte, indicating
2390 that an additional byte follows.
2391
2392
2393 The encoding for signed, two\textquoteright{s} complement LEB128
2394 (\addtoindex{SLEB128}) \addtoindexx{LEB128!signed, encoding as}
2395 numbers is similar, except that the criterion for discarding
2396 high order bytes is not whether they are zero, but whether
2397 they consist entirely of sign extension bits. Consider the
2398 4-byte integer -2. The three high level bytes of the number
2399 are sign extension, thus LEB128 would represent it as a single
2400 byte containing the low order 7 bits, with the high order
2401 bit cleared to indicate the end of the byte stream. Note
2402 that there is nothing within the LEB128 representation that
2403 indicates whether an encoded number is signed or unsigned. The
2404 decoder must know what type of number to expect.
2405 Table \refersec{tab:examplesofunsignedleb128encodings}
2406 gives some examples of unsigned LEB128\addtoindexx{LEB128!unsigned}
2407 numbers and Table \refersec{tab:examplesofsignedleb128encodings}
2408 gives some examples of signed LEB128\addtoindexx{LEB128!signed}
2409 numbers.
2410
2411 \textit{Appendix \refersec{app:variablelengthdataencodingdecodinginformative}
2412 \addtoindexx{LEB128!examples}
2413 gives algorithms for encoding and decoding these forms.}
2414
2415 \needlines{8}
2416 \begin{centering}
2417 \setlength{\extrarowheight}{0.1cm}
2418 \begin{longtable}{c|c|c}
2419   \caption{Examples of unsigned LEB128 encodings}
2420   \label{tab:examplesofunsignedleb128encodings}
2421   \addtoindexx{LEB128 encoding!examples}\addtoindexx{LEB128!unsigned} \\
2422   \hline \bfseries Number&\bfseries First byte &\bfseries Second byte \\ \hline
2423 \endfirsthead
2424   \bfseries Number&\bfseries First Byte &\bfseries Second byte\\ \hline
2425 \endhead
2426   \hline \emph{Continued on next page}
2427 \endfoot
2428   \hline
2429 \endlastfoot
2430 2&2& --- \\
2431 127&127& ---\\
2432 128& 0 + 0x80 & 1 \\
2433 129& 1 + 0x80 & 1 \\
2434 %130& 2 + 0x80 & 1 \\
2435 12857& 57 + 0x80 & 100 \\
2436 \end{longtable}
2437 \end{centering}
2438
2439
2440
2441 \begin{centering}
2442 \setlength{\extrarowheight}{0.1cm}
2443 \begin{longtable}{c|c|c}
2444   \caption{Examples of signed LEB128 encodings}
2445   \label{tab:examplesofsignedleb128encodings}
2446   \addtoindexx{LEB128!signed} \\
2447   \hline \bfseries Number&\bfseries First byte &\bfseries Second byte \\ \hline
2448 \endfirsthead
2449   \bfseries Number&\bfseries First Byte &\bfseries Second byte\\ \hline
2450 \endhead
2451   \hline \emph{Continued on next page}
2452 \endfoot
2453   \hline
2454 \endlastfoot
2455 2&2& --- \\
2456 -2&0x7e& ---\\
2457 127& 127 + 0x80 & 0 \\
2458 -127& 1 + 0x80 & 0x7f \\
2459 128& 0 + 0x80 & 1 \\
2460 -128& 0 + 0x80 & 0x7f \\
2461 129& 1 + 0x80 & 1 \\
2462 -129& 0x7f + 0x80 & 0x7e \\
2463
2464 \end{longtable}
2465 \end{centering}
2466
2467
2468
2469 \section{DWARF Expressions and Location Descriptions}
2470 \label{datarep:dwarfexpressionsandlocationdescriptions}
2471 \subsection{DWARF Expressions}
2472 \label{datarep:dwarfexpressions}
2473
2474 A
2475 \addtoindexx{DWARF expression!operator encoding}
2476 DWARF expression is stored in a \nolink{block} of contiguous
2477 bytes. The bytes form a sequence of operations. Each operation
2478 is a 1-byte code that identifies that operation, followed by
2479 zero or more bytes of additional data. The encodings for the
2480 operations are described in
2481 Table \refersec{tab:dwarfoperationencodings}.
2482
2483 \begin{centering}
2484 \setlength{\extrarowheight}{0.1cm}
2485 \begin{longtable}{l|c|c|l}
2486   \caption{DWARF operation encodings} \label{tab:dwarfoperationencodings} \\
2487   \hline & &\bfseries No. of  &\\
2488   \bfseries Operation&\bfseries Code &\bfseries Operands &\bfseries Notes\\ \hline
2489 \endfirsthead
2490    & &\bfseries No. of &\\
2491   \bfseries Operation&\bfseries Code &\bfseries  Operands &\bfseries Notes\\ \hline
2492 \endhead
2493   \hline \emph{Continued on next page}
2494 \endfoot
2495   \hline \ddag\ \textit{New in DWARF Version 5}
2496 \endlastfoot
2497
2498 \bbeb\textit{Reserved}&0x01&-& \\
2499 \bbeb\textit{Reserved}&0x02&-& \\
2500 \DWOPaddr&0x03&1 & constant address  \\
2501 & & &(size is target specific) \\
2502 \bbeb\textit{Reserved}&0x04&-& \\
2503 \bbeb\textit{Reserved}&0x05&-& \\
2504 \DWOPderef&0x06&0 & \\
2505 \bbeb\textit{Reserved}&0x07&-& \\
2506 \DWOPconstoneu&0x08&1&1-byte constant  \\
2507 \DWOPconstones&0x09&1&1-byte constant   \\
2508 \DWOPconsttwou&0x0a&1&2-byte constant   \\
2509 \DWOPconsttwos&0x0b&1&2-byte constant   \\
2510 \DWOPconstfouru&0x0c&1&4-byte constant    \\
2511 \DWOPconstfours&0x0d&1&4-byte constant   \\
2512 \DWOPconsteightu&0x0e&1&8-byte constant   \\
2513 \DWOPconsteights&0x0f&1&8-byte constant   \\
2514 \DWOPconstu&0x10&1&ULEB128 constant   \\
2515 \DWOPconsts&0x11&1&SLEB128 constant   \\
2516 \DWOPdup&0x12&0 &   \\
2517 \DWOPdrop&0x13&0  &   \\
2518 \DWOPover&0x14&0 &   \\
2519 \DWOPpick&0x15&1&1-byte stack index   \\
2520 \DWOPswap&0x16&0 &   \\
2521 \DWOProt&0x17&0 &   \\
2522 \DWOPxderef&0x18&0 &   \\
2523 \DWOPabs&0x19&0 &   \\
2524 \DWOPand&0x1a&0 &   \\
2525 \DWOPdiv&0x1b&0 &   \\
2526 \DWOPminus&0x1c&0 & \\
2527 \DWOPmod&0x1d&0 & \\
2528 \DWOPmul&0x1e&0 & \\
2529 \DWOPneg&0x1f&0 & \\
2530 \DWOPnot&0x20&0 & \\
2531 \DWOPor&0x21&0 & \\
2532 \DWOPplus&0x22&0 & \\
2533 \DWOPplusuconst&0x23&1&ULEB128 addend \\
2534 \DWOPshl&0x24&0 & \\
2535 \DWOPshr&0x25&0 & \\
2536 \DWOPshra&0x26&0 & \\
2537 \DWOPxor&0x27&0 & \\
2538
2539 \DWOPbra&0x28&1 & signed 2-byte constant \\
2540 \DWOPeq&0x29&0 & \\
2541 \DWOPge&0x2a&0 & \\
2542 \DWOPgt&0x2b&0 & \\
2543 \DWOPle&0x2c&0 & \\
2544 \DWOPlt&0x2d&0  & \\
2545 \DWOPne&0x2e&0 & \\
2546 \DWOPskip&0x2f&1&signed 2-byte constant \\ \hline
2547
2548 \DWOPlitzero & 0x30 & 0 & \\
2549 \DWOPlitone  & 0x31 & 0& literals 0 .. 31 = \\
2550 \ldots & & &\hspace{0.3cm}(\DWOPlitzero{} + literal) \\
2551 \DWOPlitthirtyone & 0x4f & 0 & \\ \hline
2552
2553 \DWOPregzero & 0x50 & 0 & \\*
2554 \DWOPregone  & 0x51 & 0&reg 0 .. 31 = \\*
2555 \ldots & & &\hspace{0.3cm}(\DWOPregzero{} + regnum) \\*
2556 \DWOPregthirtyone & 0x6f & 0 & \\ \hline
2557
2558 \DWOPbregzero & 0x70 &1 & SLEB128 offset \\*
2559 \DWOPbregone  & 0x71 & 1 &base register 0 .. 31 = \\*
2560 ... & &              &\hspace{0.3cm}(\DWOPbregzero{} + regnum) \\*
2561 \DWOPbregthirtyone & 0x8f & 1 & \\ \hline
2562
2563 \DWOPregx{} & 0x90 &1&ULEB128 register \\
2564 \DWOPfbreg{} & 0x91&1&SLEB128 offset \\
2565 \DWOPbregx{} & 0x92&2 &ULEB128 register, \\*
2566                   & & &SLEB128 offset \\
2567 \DWOPpiece{} & 0x93 &1& ULEB128 size of piece \\
2568 \DWOPderefsize{} & 0x94 &1& 1-byte size of data retrieved \\
2569 \DWOPxderefsize{} & 0x95&1&1-byte size of data retrieved \\
2570 \DWOPnop{} & 0x96 &0& \\
2571
2572 \DWOPpushobjectaddress&0x97&0 &  \\
2573 \DWOPcalltwo&0x98&1& 2-byte offset of DIE \\
2574 \DWOPcallfour&0x99&1& 4-byte offset of DIE \\
2575 \DWOPcallref&0x9a&1& 4\dash\  or 8-byte offset of DIE \\
2576 \DWOPformtlsaddress&0x9b &0& \\
2577 \DWOPcallframecfa{} &0x9c &0& \\
2578 \DWOPbitpiece&0x9d &2&ULEB128 size, \\*
2579                    &&&ULEB128 offset\\
2580 \DWOPimplicitvalue{} &0x9e &2&ULEB128 size, \\*
2581                    &&&\nolink{block} of that size\\
2582 \DWOPstackvalue{} &0x9f &0& \\
2583 \DWOPimplicitpointer{}~\ddag &0xa0& 2 &4- or 8-byte offset of DIE, \\*
2584                               &&&SLEB128 constant offset \\
2585 \DWOPaddrx~\ddag&0xa1&1&ULEB128 indirect address \\
2586 \DWOPconstx~\ddag&0xa2&1&ULEB128 indirect constant   \\
2587 \DWOPentryvalue~\ddag&0xa3&2&ULEB128 size, \\*
2588                    &&&\nolink{block} of that size\\
2589 \DWOPconsttype~\ddag    & 0xa4 & 3 & ULEB128 type entry offset,\\*
2590                                & & & 1-byte size, \\*
2591                                & & & constant value \\
2592 \DWOPregvaltype~\ddag   & 0xa5 & 2 & ULEB128 register number, \\*
2593                                  &&& ULEB128 constant offset \\
2594 \DWOPdereftype~\ddag    & 0xa6 & 2 & 1-byte size, \\*
2595                                  &&& ULEB128 type entry offset \\
2596 \DWOPxdereftype~\ddag   & 0xa7 & 2 & 1-byte size, \\*
2597                                  &&& ULEB128 type entry offset \\
2598 \DWOPconvert~\ddag      & 0xa8 & 1 & ULEB128 type entry offset \\
2599 \DWOPreinterpret~\ddag  & 0xa9 & 1 & ULEB128 type entry offset \\
2600 \DWOPlouser{} &0xe0 && \\
2601 \DWOPhiuser{} &\xff && \\
2602
2603 \end{longtable}
2604 \end{centering}
2605
2606
2607 \subsection{Location Descriptions}
2608 \label{datarep:locationdescriptions}
2609
2610 A location description is used to compute the
2611 location of a variable or other entity.
2612
2613 \subsection{Location Lists}
2614 \label{datarep:locationlists}
2615 Each entry in a \addtoindex{location list} is either a location list entry,
2616 a base address entry, a default location entry or an
2617 \addtoindexx{end-of-list entry!in location list}
2618 end-of-list entry.
2619
2620 Each entry begins with an unsigned 1-byte code that indicates the kind of entry
2621 that follows. The encodings for these constants are given in
2622 Table \ref{tab:locationlistentryencodingvalues}.
2623
2624 \needlines{10}
2625 \begin{centering}
2626 \setlength{\extrarowheight}{0.1cm}
2627 \begin{longtable}{l|c}
2628   \caption{Location list entry encoding values}
2629   \label{tab:locationlistentryencodingvalues} \\
2630   \hline \bfseries Location list entry encoding name&\bfseries Value \\ \hline
2631 \endfirsthead
2632   \bfseries Location list entry encoding name&\bfseries Value\\ \hline
2633 \endhead
2634   \hline \emph{Continued on next page}
2635 \endfoot
2636   \hline
2637   \ddag New in \DWARFVersionV
2638 \endlastfoot
2639 \DWLLEendoflist~\ddag & 0x00 \\
2640 \DWLLEbaseaddressx~\ddag & 0x01 \\
2641 \DWLLEstartxendx~\ddag & 0x02 \\
2642 \DWLLEstartxlength~\ddag & 0x03 \\
2643 \DWLLEoffsetpair~\ddag & 0x04 \\
2644 \DWLLEdefaultlocation~\ddag & 0x05 \\
2645 \DWLLEbaseaddress~\ddag & 0x06 \\
2646 \DWLLEstartend~\ddag & 0x07 \\
2647 \DWLLEstartlength~\ddag & 0x08 \\
2648 \end{longtable}
2649 \end{centering}
2650
2651 \section{Base Type Attribute Encodings}
2652 \label{datarep:basetypeattributeencodings}
2653
2654 The\hypertarget{chap:DWATencodingencodingofbasetype}{}
2655 encodings of the constants used in the
2656 \DWATencodingDEFN{} attribute\addtoindexx{encoding attribute}
2657 are given in
2658 Table \refersec{tab:basetypeencodingvalues}
2659
2660 \begin{centering}
2661 \setlength{\extrarowheight}{0.1cm}
2662 \begin{longtable}{l|c}
2663   \caption{Base type encoding values} \label{tab:basetypeencodingvalues} \\
2664   \hline \bfseries Base type encoding name&\bfseries Value \\ \hline
2665 \endfirsthead
2666   \bfseries Base type encoding name&\bfseries Value\\ \hline
2667 \endhead
2668   \hline \emph{Continued on next page}
2669 \endfoot
2670   \hline
2671   \ddag \ \textit{New in \DWARFVersionV}
2672 \endlastfoot
2673 \DWATEaddress&0x01 \\
2674 \DWATEboolean&0x02 \\
2675 \DWATEcomplexfloat&0x03 \\
2676 \DWATEfloat&0x04 \\
2677 \DWATEsigned&0x05 \\
2678 \DWATEsignedchar&0x06 \\
2679 \DWATEunsigned&0x07 \\
2680 \DWATEunsignedchar&0x08 \\
2681 \DWATEimaginaryfloat&0x09 \\
2682 \DWATEpackeddecimal&0x0a \\
2683 \DWATEnumericstring&0x0b \\
2684 \DWATEedited&0x0c \\
2685 \DWATEsignedfixed&0x0d \\
2686 \DWATEunsignedfixed&0x0e \\
2687 \DWATEdecimalfloat & 0x0f \\
2688 \DWATEUTF{} & 0x10 \\
2689 \DWATEUCS~\ddag   & 0x11 \\
2690 \DWATEASCII~\ddag & 0x12 \\
2691 \DWATElouser{} & 0x80 \\
2692 \DWATEhiuser{} & \xff \\
2693 \end{longtable}
2694 \end{centering}
2695
2696 \vspace*{1cm}
2697 The encodings of the constants used in the
2698 \DWATdecimalsign{} attribute
2699 are given in
2700 Table \refersec{tab:decimalsignencodings}.
2701
2702 \begin{centering}
2703 \setlength{\extrarowheight}{0.1cm}
2704 \begin{longtable}{l|c}
2705   \caption{Decimal sign encodings} \label{tab:decimalsignencodings} \\
2706   \hline \bfseries Decimal sign code name&\bfseries Value \\ \hline
2707 \endfirsthead
2708   \bfseries Decimal sign code name&\bfseries Value\\ \hline
2709 \endhead
2710 %  \hline \emph{Continued on next page}
2711 %\endfoot
2712   \hline
2713 \endlastfoot
2714 \DWDSunsigned{}          & 0x01  \\
2715 \DWDSleadingoverpunch{}  & 0x02  \\
2716 \DWDStrailingoverpunch{} & 0x03  \\
2717 \DWDSleadingseparate{}   & 0x04  \\
2718 \DWDStrailingseparate{}  & 0x05 \\
2719 \end{longtable}
2720 \end{centering}
2721
2722 \needlines{9}
2723 The encodings of the constants used in the
2724 \DWATendianity{} attribute are given in
2725 Table \refersec{tab:endianityencodings}.
2726
2727 \begin{centering}
2728 \setlength{\extrarowheight}{0.1cm}
2729 \begin{longtable}{l|c}
2730   \caption{Endianity encodings} \label{tab:endianityencodings}\\
2731   \hline \bfseries Endian code name&\bfseries Value \\ \hline
2732 \endfirsthead
2733   \bfseries Endian code name&\bfseries Value\\ \hline
2734 \endhead
2735   \hline \emph{Continued on next page}
2736 \endfoot
2737   \hline
2738 \endlastfoot
2739
2740 \DWENDdefault{}  & 0x00 \\
2741 \DWENDbig{} & 0x01 \\
2742 \DWENDlittle{} & 0x02 \\
2743 \DWENDlouser{} & 0x40 \\
2744 \DWENDhiuser{} & \xff \\
2745
2746 \end{longtable}
2747 \end{centering}
2748
2749 \needlines{10}
2750 \section{Accessibility Codes}
2751 \label{datarep:accessibilitycodes}
2752 The encodings of the constants used in the
2753 \DWATaccessibility{}
2754 attribute
2755 \addtoindexx{accessibility attribute}
2756 are given in
2757 Table \refersec{tab:accessibilityencodings}.
2758
2759 \begin{centering}
2760 \setlength{\extrarowheight}{0.1cm}
2761 \begin{longtable}{l|c}
2762   \caption{Accessibility encodings} \label{tab:accessibilityencodings}\\
2763   \hline \bfseries Accessibility code name&\bfseries Value \\ \hline
2764 \endfirsthead
2765   \bfseries Accessibility code name&\bfseries Value\\ \hline
2766 \endhead
2767   \hline \emph{Continued on next page}
2768 \endfoot
2769   \hline
2770 \endlastfoot
2771
2772 \DWACCESSpublic&0x01  \\
2773 \DWACCESSprotected&0x02 \\
2774 \DWACCESSprivate&0x03 \\
2775
2776 \end{longtable}
2777 \end{centering}
2778
2779
2780 \section{Visibility Codes}
2781 \label{datarep:visibilitycodes}
2782 The encodings of the constants used in the
2783 \DWATvisibility{} attribute are given in
2784 Table \refersec{tab:visibilityencodings}.
2785
2786 \begin{centering}
2787 \setlength{\extrarowheight}{0.1cm}
2788 \begin{longtable}{l|c}
2789   \caption{Visibility encodings} \label{tab:visibilityencodings}\\
2790   \hline \bfseries Visibility code name&\bfseries Value \\ \hline
2791 \endfirsthead
2792   \bfseries Visibility code name&\bfseries Value\\ \hline
2793 \endhead
2794   \hline \emph{Continued on next page}
2795 \endfoot
2796   \hline
2797 \endlastfoot
2798
2799 \DWVISlocal&0x01 \\
2800 \DWVISexported&0x02 \\
2801 \DWVISqualified&0x03 \\
2802
2803 \end{longtable}
2804 \end{centering}
2805
2806 \section{Virtuality Codes}
2807 \label{datarep:vitualitycodes}
2808
2809 The encodings of the constants used in the
2810 \DWATvirtuality{} attribute are given in
2811 Table \refersec{tab:virtualityencodings}.
2812
2813 \begin{centering}
2814 \setlength{\extrarowheight}{0.1cm}
2815 \begin{longtable}{l|c}
2816   \caption{Virtuality encodings} \label{tab:virtualityencodings}\\
2817   \hline \bfseries Virtuality code name&\bfseries Value \\ \hline
2818 \endfirsthead
2819   \bfseries Virtuality code name&\bfseries Value\\ \hline
2820 \endhead
2821   \hline \emph{Continued on next page}
2822 \endfoot
2823   \hline
2824 \endlastfoot
2825
2826 \DWVIRTUALITYnone&0x00 \\
2827 \DWVIRTUALITYvirtual&0x01 \\
2828 \DWVIRTUALITYpurevirtual&0x02 \\
2829
2830 \end{longtable}
2831 \end{centering}
2832
2833 \needlines{4}
2834 The value
2835 \DWVIRTUALITYnone{} is equivalent to the absence of the
2836 \DWATvirtuality{}
2837 attribute.
2838
2839 \section{Source Languages}
2840 \label{datarep:sourcelanguages}
2841
2842 The encodings of the constants used
2843 \addtoindexx{language attribute, encoding}
2844 in
2845 \addtoindexx{language name encoding}
2846 the
2847 \DWATlanguage{}
2848 attribute are given in
2849 Table \refersec{tab:languageencodings}.
2850 Names marked with
2851 % If we don't force a following space it looks odd
2852 \dag \
2853 and their associated values are reserved, but the
2854 languages they represent are not well supported.
2855 Table \refersec{tab:languageencodings}
2856 also shows the
2857 \addtoindexx{lower bound attribute!default}
2858 default lower bound, if any, assumed for
2859 an omitted \DWATlowerbound{} attribute in the context of a
2860 \DWTAGsubrangetype{} debugging information entry for each
2861 defined language.
2862
2863 \begin{centering}
2864 \setlength{\extrarowheight}{0.1cm}
2865 \begin{longtable}{l|c|c}
2866   \caption{Language encodings} \label{tab:languageencodings}\\
2867   \hline \bfseries Language name&\bfseries Value &\bfseries Default Lower Bound \\ \hline
2868 \endfirsthead
2869   \bfseries Language name&\bfseries Value &\bfseries Default Lower Bound\\ \hline
2870 \endhead
2871   \hline \emph{Continued on next page}
2872 \endfoot
2873   \hline
2874   \dag \ \textit{See text} \\ \ddag \ \textit{New in \DWARFVersionV}
2875 \endlastfoot
2876 \addtoindexx{ISO-defined language names}
2877
2878 \DWLANGCeightynine &0x0001 &0 \addtoindexx{C:1989 (ISO)}      \\
2879 \DWLANGC{} &0x0002 &0  \addtoindexx{C!non-standard} \\
2880 \DWLANGAdaeightythree{} \dag &0x0003 &1  \addtoindexx{Ada:1983 (ISO)}     \\
2881 \DWLANGCplusplus{} &0x0004 &0 \addtoindexx{C++98 (ISO)} \\
2882 \DWLANGCobolseventyfour{} \dag &0x0005 &1 \addtoindexx{COBOL:1974 (ISO)}      \\
2883 \DWLANGCoboleightyfive{} \dag &0x0006 &1 \addtoindexx{COBOL:1985 (ISO)}      \\
2884 \DWLANGFortranseventyseven &0x0007 &1 \addtoindexx{FORTRAN:1977 (ISO)}      \\
2885 \DWLANGFortranninety &0x0008 &1 \addtoindexx{Fortran:1990 (ISO)}      \\
2886 \DWLANGPascaleightythree &0x0009 &1 \addtoindexx{Pascal:1983 (ISO)}      \\
2887 \DWLANGModulatwo &0x000a &1 \addtoindexx{Modula-2:1996 (ISO)}      \\
2888 \DWLANGJava &0x000b &0 \addtoindexx{Java}      \\
2889 \DWLANGCninetynine &0x000c &0 \addtoindexx{C:1999 (ISO)}      \\
2890 \DWLANGAdaninetyfive{} \dag &0x000d &1 \addtoindexx{Ada:1995 (ISO)}      \\
2891 \DWLANGFortranninetyfive &0x000e &1 \addtoindexx{Fortran:1995 (ISO)}      \\
2892 \DWLANGPLI{} \dag &0x000f &1 \addtoindexx{PL/I:1976 (ANSI)}\\
2893 \DWLANGObjC{} &0x0010 &0 \addtoindexx{Objective C}\\
2894 \DWLANGObjCplusplus{} &0x0011 &0 \addtoindexx{Objective C++}\\
2895 \DWLANGUPC{} &0x0012 &0 \addtoindexx{UPC}\\
2896 \DWLANGD{} &0x0013 &0 \addtoindexx{D language}\\
2897 \DWLANGPython{} \dag &0x0014 &0 \addtoindexx{Python}\\
2898 \DWLANGOpenCL{} \dag \ddag &0x0015 &0 \addtoindexx{OpenCL}\\
2899 \DWLANGGo{} \dag \ddag &0x0016 &0 \addtoindexx{Go}\\
2900 \DWLANGModulathree{} \dag \ddag &0x0017 &1 \addtoindexx{Modula-3}\\
2901 \DWLANGHaskell{} \dag \ddag &0x0018 &0 \addtoindexx{Haskell}\\
2902 \DWLANGCpluspluszerothree{} \ddag &0x0019 &0 \addtoindexx{C++03 (ISO)}\\
2903 \DWLANGCpluspluseleven{} \ddag &0x001a &0 \addtoindexx{C++11 (ISO)} \\
2904 \DWLANGOCaml{} \ddag &0x001b &0 \addtoindexx{OCaml}\\
2905 \DWLANGRust{} \ddag &0x001c &0 \addtoindexx{Rust}\\
2906 \DWLANGCeleven{} \ddag &0x001d &0 \addtoindexx{C:2011 (ISO)}\\
2907 \DWLANGSwift{} \ddag &0x001e &0 \addtoindexx{Swift} \\
2908 \DWLANGJulia{} \ddag &0x001f &1 \addtoindexx{Julia} \\
2909 \DWLANGDylan{} \ddag &0x0020 &0 \addtoindexx{Dylan} \\
2910 \DWLANGCplusplusfourteen{}~\ddag &0x0021 &0 \addtoindexx{C++14 (ISO)} \\
2911 \DWLANGFortranzerothree{}~\ddag  &0x0022 &1 \addtoindexx{Fortran:2004 (ISO)} \\
2912 \DWLANGFortranzeroeight{}~\ddag  &0x0023 &1 \addtoindexx{Fortran:2010 (ISO)} \\
2913 \DWLANGRenderScript{}~\ddag       &0x0024 &0 \addtoindexx{RenderScript Kernel Language} \\
2914 \bb
2915 \DWLANGBLISS{} \ddag &0x0025 &0 \addtoindexx{BLISS}
2916 \eb
2917 \\
2918 \DWLANGlouser{} &0x8000 & \\
2919 \DWLANGhiuser{} &\xffff & \\
2920
2921 \end{longtable}
2922 \end{centering}
2923
2924 \section{Address Class Encodings}
2925 \label{datarep:addressclassencodings}
2926
2927 The value of the common
2928 \addtoindex{address class} encoding
2929 \DWADDRnone{} is 0.
2930
2931 \needlines{16}
2932 \section{Identifier Case}
2933 \label{datarep:identifiercase}
2934
2935 The encodings of the constants used in the
2936 \DWATidentifiercase{} attribute are given in
2937 Table \refersec{tab:identifiercaseencodings}.
2938
2939 \needlines{8}
2940 \begin{centering}
2941 \setlength{\extrarowheight}{0.1cm}
2942 \begin{longtable}{l|c}
2943   \caption{Identifier case encodings} \label{tab:identifiercaseencodings}\\
2944   \hline \bfseries Identifier case name&\bfseries Value \\ \hline
2945 \endfirsthead
2946   \bfseries Identifier case name&\bfseries Value\\ \hline
2947 \endhead
2948   \hline \emph{Continued on next page}
2949 \endfoot
2950   \hline
2951 \endlastfoot
2952 \DWIDcasesensitive&0x00     \\
2953 \DWIDupcase&0x01     \\
2954 \DWIDdowncase&0x02     \\
2955 \DWIDcaseinsensitive&0x03     \\
2956 \end{longtable}
2957 \end{centering}
2958
2959 \needlines{8}
2960 \section{Calling Convention Encodings}
2961 \label{datarep:callingconventionencodings}
2962 The encodings of the constants used in the
2963 \DWATcallingconvention{} attribute are given in
2964 Table \refersec{tab:callingconventionencodings}.
2965
2966 \begin{centering}
2967 \setlength{\extrarowheight}{0.1cm}
2968 \begin{longtable}{l|c}
2969   \caption{Calling convention encodings} \label{tab:callingconventionencodings}\\
2970   \hline \bfseries Calling convention name&\bfseries Value \\ \hline
2971 \endfirsthead
2972   \bfseries Calling convention name&\bfseries Value\\ \hline
2973 \endhead
2974   \hline \emph{Continued on next page}
2975 \endfoot
2976   \hline \ddag\ \textit{New in DWARF Version 5}
2977 \endlastfoot
2978
2979 \DWCCnormal &0x01     \\
2980 \DWCCprogram&0x02     \\
2981 \DWCCnocall &0x03     \\
2982 \DWCCpassbyreference~\ddag &0x04 \\
2983 \DWCCpassbyvalue~\ddag     &0x05 \\
2984 \DWCClouser &0x40     \\
2985 \DWCChiuser&\xff     \\
2986
2987 \end{longtable}
2988 \end{centering}
2989
2990 \needlines{12}
2991 \section{Inline Codes}
2992 \label{datarep:inlinecodes}
2993
2994 The encodings of the constants used in
2995 \addtoindexx{inline attribute}
2996 the
2997 \DWATinline{} attribute are given in
2998 Table \refersec{tab:inlineencodings}.
2999
3000 \needlines{8}
3001 \begin{centering}
3002 \setlength{\extrarowheight}{0.1cm}
3003 \begin{longtable}{l|c}
3004   \caption{Inline encodings} \label{tab:inlineencodings}\\
3005   \hline \bfseries Inline code name&\bfseries Value \\ \hline
3006 \endfirsthead
3007   \bfseries Inline Code name&\bfseries Value\\ \hline
3008 \endhead
3009   \hline \emph{Continued on next page}
3010 \endfoot
3011   \hline
3012 \endlastfoot
3013
3014 \DWINLnotinlined&0x00      \\
3015 \DWINLinlined&0x01      \\
3016 \DWINLdeclarednotinlined&0x02      \\
3017 \DWINLdeclaredinlined&0x03      \\
3018
3019 \end{longtable}
3020 \end{centering}
3021
3022 % this clearpage is ugly, but the following table came
3023 % out oddly without it.
3024
3025 \needlines{10}
3026 \section{Array Ordering}
3027 \label{datarep:arrayordering}
3028
3029 The encodings of the constants used in the
3030 \DWATordering{} attribute are given in
3031 Table \refersec{tab:orderingencodings}.
3032
3033 \needlines{8}
3034 \begin{centering}
3035 \setlength{\extrarowheight}{0.1cm}
3036 \begin{longtable}{l|c}
3037   \caption{Ordering encodings} \label{tab:orderingencodings}\\
3038   \hline \bfseries Ordering name&\bfseries Value \\ \hline
3039 \endfirsthead
3040   \bfseries Ordering name&\bfseries Value\\ \hline
3041 \endhead
3042   \hline \emph{Continued on next page}
3043 \endfoot
3044   \hline
3045 \endlastfoot
3046
3047 \DWORDrowmajor&0x00  \\
3048 \DWORDcolmajor&0x01  \\
3049
3050 \end{longtable}
3051 \end{centering}
3052
3053
3054 \section{Discriminant Lists}
3055 \label{datarep:discriminantlists}
3056
3057 The descriptors used in
3058 \addtoindexx{discriminant list attribute}
3059 the
3060 \DWATdiscrlist{} attribute are
3061 encoded as 1-byte constants. The
3062 defined values are given in
3063 Table \refersec{tab:discriminantdescriptorencodings}.
3064
3065 % Odd that the 'Name' field capitalized here, it is not caps elsewhere.
3066 \begin{centering}
3067 \setlength{\extrarowheight}{0.1cm}
3068 \begin{longtable}{l|c}
3069   \caption{Discriminant descriptor encodings} \label{tab:discriminantdescriptorencodings}\\
3070   \hline \bfseries Descriptor name&\bfseries Value \\ \hline
3071 \endfirsthead
3072   \bfseries Descriptor name&\bfseries Value\\ \hline
3073 \endhead
3074   \hline \emph{Continued on next page}
3075 \endfoot
3076   \hline
3077 \endlastfoot
3078
3079 \DWDSClabel&0x00 \\
3080 \DWDSCrange&0x01 \\
3081
3082 \end{longtable}
3083 \end{centering}
3084
3085 \needlines{6}
3086 \section{Name Index Table}
3087 \label{datarep:nameindextable}
3088 The \addtoindexi{version number}{version number!name index table}
3089 in the name index table header is \versiondotdebugnames{}.
3090
3091 The name index attributes and their encodings are listed in Table \refersec{datarep:indexattributeencodings}.
3092
3093 \needlines{14}
3094 \begin{centering}
3095 \setlength{\extrarowheight}{0.1cm}
3096 \begin{longtable}{l|c|l}
3097   \caption{Name index attribute encodings} \label{datarep:indexattributeencodings}\\
3098   \hline \bfseries Attribute name &\bfseries Value &\bfseries Form/Class \\ \hline
3099 \endfirsthead
3100   \bfseries Attribute name &\bfseries Value &\bfseries Form/Class \\ \hline
3101 \endhead
3102   \hline \emph{Continued on next page}
3103 \endfoot
3104   \hline
3105   \ddag~\textit{New in \DWARFVersionV}
3106 \endlastfoot
3107 \DWIDXcompileunit~\ddag & 1        & \CLASSconstant \\
3108 \DWIDXtypeunit~\ddag    & 2        & \CLASSconstant \\
3109 \DWIDXdieoffset~\ddag   & 3        & \CLASSreference \\
3110 \DWIDXparent~\ddag      & 4        & \CLASSconstant \\
3111 \DWIDXtypehash~\ddag    & 5        & \DWFORMdataeight \\
3112 \DWIDXlouser~\ddag      & 0x2000   & \\
3113 \DWIDXhiuser~\ddag      & \xiiifff & \\
3114 \end{longtable}
3115 \end{centering}
3116
3117 The abbreviations table ends with an entry consisting of a single 0
3118 byte for the abbreviation code. The size of the table given by
3119 \texttt{abbrev\_table\_size} may include optional padding following the
3120 terminating 0 byte.
3121
3122 \section{Defaulted Member Encodings}
3123 \hypertarget{datarep:defaultedmemberencodings}{}
3124
3125 The encodings of the constants used in the \DWATdefaulted{} attribute
3126 are given in Table \referfol{datarep:defaultedattributeencodings}.
3127
3128 \begin{centering}
3129 \setlength{\extrarowheight}{0.1cm}
3130 \begin{longtable}{l|c}
3131   \caption{Defaulted attribute encodings} \label{datarep:defaultedattributeencodings} \\
3132   \hline \bfseries Defaulted name &\bfseries Value \\ \hline
3133 \endfirsthead
3134   \bfseries Defaulted name &\bfseries Value \\ \hline
3135 \endhead
3136   \hline \emph{Continued on next page}
3137 \endfoot
3138   \hline
3139   \ddag~\textit{New in \DWARFVersionV}
3140 \endlastfoot
3141 \DWDEFAULTEDno~\ddag   & 0x00 \\
3142 \DWDEFAULTEDinclass~\ddag       & 0x01 \\
3143 \DWDEFAULTEDoutofclass~\ddag    & 0x02 \\
3144 \end{longtable}
3145 \end{centering}
3146
3147 \needlines{10}
3148 \section{Address Range Table}
3149 \label{datarep:addrssrangetable}
3150
3151 Each set of entries in the table of address ranges contained
3152 in the \dotdebugaranges{}
3153 section begins with a header containing:
3154 \begin{enumerate}[1. ]
3155 % FIXME The unit length text is not fully consistent across
3156 % these tables.
3157
3158 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
3159 \addttindexx{unit\_length}
3160 A 4-byte or 12-byte length containing the length of the
3161 \addtoindexx{initial length}
3162 set of entries for this compilation unit, not including the
3163 length field itself. In the \thirtytwobitdwarfformat, this is a
3164 4-byte unsigned integer (which must be less than \xfffffffzero);
3165 in the \sixtyfourbitdwarfformat, this consists of the 4-byte value
3166 \wffffffff followed by an 8-byte unsigned integer that gives
3167 the actual length
3168 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
3169
3170 \item version (\HFTuhalf) \\
3171 A 2-byte version identifier representing the version of the
3172 DWARF information for the address range table.
3173
3174 This value in this field \addtoindexx{version number!address range table} is 2.
3175
3176 \item debug\_info\_offset (\livelink{datarep:sectionoffsetlength}{section offset}) \\
3177 A
3178 \addtoindexx{section offset!in .debug\_aranges header}
3179 4-byte or 8-byte offset into the
3180 \dotdebuginfo{} section of
3181 the compilation unit header. In the \thirtytwobitdwarfformat,
3182 this is a 4-byte unsigned offset; in the \sixtyfourbitdwarfformat,
3183 this is an 8-byte unsigned offset
3184 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
3185
3186 \item \texttt{address\_size} (\HFTubyte) \\
3187 A 1-byte unsigned integer containing the size in bytes of an
3188 \addttindexx{address\_size}
3189 address
3190 \addtoindexx{size of an address}
3191 (or the offset portion of an address for segmented
3192 \addtoindexx{address space!segmented}
3193 addressing) on the target system.
3194
3195 \item \HFNsegmentselectorsize{} (\HFTubyte) \\
3196 A 1-byte unsigned integer containing the size in bytes of a
3197 segment selector on the target system.
3198
3199 \end{enumerate}
3200
3201 This header is followed by a series of tuples. Each tuple
3202 consists of a segment, an address and a length.
3203 The segment selector
3204 size is given by the \HFNsegmentselectorsize{} field of the header; the
3205 address and length size are each given by the \addttindex{address\_size}
3206 field of the header.
3207 The first tuple following the header in
3208 each set begins at an offset that is a multiple of the size
3209 of a single tuple (that is, the size of a segment selector
3210 plus twice the \addtoindex{size of an address}).
3211 The header is padded, if
3212 necessary, to that boundary. Each set of tuples is terminated
3213 by a 0 for the segment, a 0 for the address and 0 for the
3214 length. If the \HFNsegmentselectorsize{} field in the header is zero,
3215 the segment selectors are omitted from all tuples, including
3216 the terminating tuple.
3217
3218
3219 \section{Line Number Information}
3220 \label{datarep:linenumberinformation}
3221
3222 The \addtoindexi{version number}{version number!line number information}
3223 in the line number program header is \versiondotdebugline{}.
3224
3225 The boolean values \doublequote{true} and \doublequote{false}
3226 used by the line number information program are encoded
3227 as a single byte containing the value 0
3228 for \doublequote{false,} and a non-zero value for \doublequote{true.}
3229
3230 \needlines{10}
3231 The encodings for the standard opcodes are given in
3232 \addtoindexx{line number opcodes!standard opcode encoding}
3233 Table \refersec{tab:linenumberstandardopcodeencodings}.
3234
3235 \begin{centering}
3236 \setlength{\extrarowheight}{0.1cm}
3237 \begin{longtable}{l|c}
3238   \caption{Line number standard opcode encodings} \label{tab:linenumberstandardopcodeencodings}\\
3239   \hline \bfseries Opcode name&\bfseries Value \\ \hline
3240 \endfirsthead
3241   \bfseries Opcode name&\bfseries Value\\ \hline
3242 \endhead
3243   \hline \emph{Continued on next page}
3244 \endfoot
3245   \hline
3246 \endlastfoot
3247
3248 \DWLNScopy&0x01 \\
3249 \DWLNSadvancepc&0x02 \\
3250 \DWLNSadvanceline&0x03 \\
3251 \DWLNSsetfile&0x04 \\
3252 \DWLNSsetcolumn&0x05 \\
3253 \DWLNSnegatestmt&0x06 \\
3254 \DWLNSsetbasicblock&0x07 \\
3255 \DWLNSconstaddpc&0x08 \\
3256 \DWLNSfixedadvancepc&0x09 \\
3257 \DWLNSsetprologueend&0x0a \\*
3258 \DWLNSsetepiloguebegin&0x0b \\*
3259 \DWLNSsetisa&0x0c \\*
3260 \end{longtable}
3261 \end{centering}
3262
3263 \clearpage
3264 \needlines{12}
3265 The encodings for the extended opcodes are given in
3266 \addtoindexx{line number opcodes!extended opcode encoding}
3267 Table \refersec{tab:linenumberextendedopcodeencodings}.
3268
3269 \begin{centering}
3270 \setlength{\extrarowheight}{0.1cm}
3271 \begin{longtable}{l|c}
3272   \caption{Line number extended opcode encodings} \label{tab:linenumberextendedopcodeencodings}\\
3273   \hline \bfseries Opcode name&\bfseries Value \\ \hline
3274 \endfirsthead
3275   \bfseries Opcode name&\bfseries Value\\ \hline
3276 \endhead
3277   \hline \emph{Continued on next page}
3278 \endfoot
3279   \hline %\ddag~\textit{New in DWARF Version 5}
3280 \endlastfoot
3281
3282 \DWLNEendsequence       &0x01 \\
3283 \DWLNEsetaddress        &0x02 \\
3284 \textit{Reserved}       &0x03\footnote{Code 0x03 is reserved to allow backward compatible support of the
3285                                        DW\_LNE\_define\_file operation which was defined in \DWARFVersionIV{}
3286                                        and earlier.} \\
3287 \DWLNEsetdiscriminator  &0x04 \\
3288 \DWLNElouser            &0x80 \\
3289 \DWLNEhiuser            &\xff \\
3290
3291 \end{longtable}
3292 \end{centering}
3293
3294 \needlines{6}
3295 The encodings for the line number header entry formats are given in
3296 \addtoindexx{line number opcodes!file entry format encoding}
3297 Table \refersec{tab:linenumberheaderentryformatencodings}.
3298
3299 \begin{centering}
3300 \setlength{\extrarowheight}{0.1cm}
3301 \begin{longtable}{l|c}
3302   \caption{Line number header entry format \mbox{encodings}} \label{tab:linenumberheaderentryformatencodings}\\
3303   \hline \bfseries Line number header entry format name&\bfseries Value \\ \hline
3304 \endfirsthead
3305   \bfseries Line number header entry format name&\bfseries Value\\ \hline
3306 \endhead
3307   \hline \emph{Continued on next page}
3308 \endfoot
3309   \hline \ddag~\textit{New in DWARF Version 5}
3310 \endlastfoot
3311 \DWLNCTpath~\ddag           & 0x1 \\
3312 \DWLNCTdirectoryindex~\ddag & 0x2 \\
3313 \DWLNCTtimestamp~\ddag      & 0x3 \\
3314 \DWLNCTsize~\ddag           & 0x4 \\
3315 \DWLNCTMDfive~\ddag         & 0x5 \\
3316 \DWLNCTlouser~\ddag         & 0x2000 \\
3317 \DWLNCThiuser~\ddag         & \xiiifff \\
3318 \end{longtable}
3319 \end{centering}
3320
3321 \needlines{6}
3322 \section{Macro Information}
3323 \label{datarep:macroinformation}
3324 The \addtoindexi{version number}{version number!macro information}
3325 in the macro information header is \versiondotdebugmacro{}.
3326
3327 The source line numbers and source file indices encoded in the
3328 macro information section are represented as
3329 unsigned LEB128\addtoindexx{LEB128!unsigned} numbers.
3330
3331 \needlines{4}
3332 The macro information entry type is encoded as a single unsigned byte.
3333 The encodings
3334 \addtoindexx{macro information entry types!encoding}
3335 are given in
3336 Table \refersec{tab:macroinfoentrytypeencodings}.
3337
3338 \needlines{10}
3339 \begin{centering}
3340 \setlength{\extrarowheight}{0.1cm}
3341 \begin{longtable}{l|c}
3342   \caption{Macro information entry type encodings} \label{tab:macroinfoentrytypeencodings}\\
3343   \hline \bfseries Macro information entry type name&\bfseries Value \\ \hline
3344 \endfirsthead
3345   \bfseries Macro information entry type name&\bfseries Value\\ \hline
3346 \endhead
3347   \hline \emph{Continued on next page}
3348 \endfoot
3349   \hline \ddag~\textit{New in DWARF Version 5}
3350 \endlastfoot
3351
3352 \DWMACROdefine~\ddag          &0x01 \\
3353 \DWMACROundef~\ddag           &0x02 \\
3354 \DWMACROstartfile~\ddag       &0x03 \\
3355 \DWMACROendfile~\ddag         &0x04 \\
3356 \DWMACROdefinestrp~\ddag      &0x05 \\
3357 \DWMACROundefstrp~\ddag       &0x06 \\
3358 \DWMACROimport~\ddag          &0x07 \\
3359 \DWMACROdefinesup~\ddag       &0x08 \\
3360 \DWMACROundefsup~\ddag        &0x09 \\
3361 \DWMACROimportsup~\ddag       &0x0a \\
3362 \DWMACROdefinestrx~\ddag      &0x0b \\
3363 \DWMACROundefstrx~\ddag       &0x0c \\
3364 \DWMACROlouser~\ddag          &0xe0 \\
3365 \DWMACROhiuser~\ddag          &\xff \\
3366
3367 \end{longtable}
3368 \end{centering}
3369
3370 \needlines{7}
3371 \section{Call Frame Information}
3372 \label{datarep:callframeinformation}
3373
3374 In the \thirtytwobitdwarfformat, the value of the CIE id in the
3375 CIE header is \xffffffff; in the \sixtyfourbitdwarfformat, the
3376 value is \xffffffffffffffff.
3377
3378 The value of the CIE \addtoindexi{version number}{version number!call frame information}
3379 is \versiondotdebugframe.
3380
3381 Call frame instructions are encoded in one or more bytes. The
3382 primary opcode is encoded in the high order two bits of
3383 the first byte (that is, opcode = byte $\gg$ 6). An operand
3384 or extended opcode may be encoded in the low order 6
3385 bits. Additional operands are encoded in subsequent bytes.
3386 The instructions and their encodings are presented in
3387 Table \refersec{tab:callframeinstructionencodings}.
3388
3389 \begin{centering}
3390 \setlength{\extrarowheight}{0.1cm}
3391 \begin{longtable}{l|c|c|l|l}
3392   \caption{Call frame instruction encodings} \label{tab:callframeinstructionencodings} \\
3393   \hline &\bfseries High 2 &\bfseries Low 6 &  & \\
3394   \bfseries Instruction&\bfseries Bits &\bfseries Bits &\bfseries Operand 1 &\bfseries Operand 2\\ \hline
3395 \endfirsthead
3396    & \bfseries High 2 &\bfseries Low 6 &  &\\
3397   \bfseries Instruction&\bfseries Bits &\bfseries Bits &\bfseries Operand 1 &\bfseries Operand 2\\ \hline
3398 \endhead
3399   \hline \emph{Continued on next page}
3400 \endfoot
3401   \hline
3402 \endlastfoot
3403
3404 \DWCFAadvanceloc&0x1&delta & \\
3405 \DWCFAoffset&0x2&register&ULEB128 offset \\
3406 \DWCFArestore&0x3&register & & \\
3407 \DWCFAnop&0&0 & & \\
3408 \DWCFAsetloc&0&0x01&address & \\
3409 \DWCFAadvancelocone&0&0x02&1-byte delta & \\
3410 \DWCFAadvanceloctwo&0&0x03&2-byte delta & \\
3411 \DWCFAadvancelocfour&0&0x04&4-byte delta & \\
3412 \DWCFAoffsetextended&0&0x05&ULEB128 register&ULEB128 offset \\
3413 \DWCFArestoreextended&0&0x06&ULEB128 register & \\
3414 \DWCFAundefined&0&0x07&ULEB128 register & \\
3415 \DWCFAsamevalue&0&0x08 &ULEB128 register & \\
3416 \DWCFAregister&0&0x09&ULEB128 register &ULEB128 offset \\
3417 \DWCFArememberstate&0&0x0a & & \\
3418 \DWCFArestorestate&0&0x0b & & \\
3419 \DWCFAdefcfa&0&0x0c &ULEB128 register&ULEB128 offset \\
3420 \DWCFAdefcfaregister&0&0x0d&ULEB128 register & \\
3421 \DWCFAdefcfaoffset&0&0x0e &ULEB128 offset & \\
3422 \DWCFAdefcfaexpression&0&0x0f &BLOCK  \\
3423 \DWCFAexpression&0&0x10&ULEB128 register & BLOCK \\
3424
3425 \DWCFAoffsetextendedsf&0&0x11&ULEB128 register&SLEB128 offset \\
3426 \DWCFAdefcfasf&0&0x12&ULEB128 register&SLEB128 offset \\
3427 \DWCFAdefcfaoffsetsf&0&0x13&SLEB128 offset & \\
3428 \DWCFAvaloffset&0&0x14&ULEB128&ULEB128 \\
3429 \DWCFAvaloffsetsf&0&0x15&ULEB128&SLEB128 \\
3430 \DWCFAvalexpression&0&0x16&ULEB128&BLOCK  \\
3431 \DWCFAlouser&0&0x1c   & & \\
3432 \DWCFAhiuser&0&\xiiif & & \\
3433 \end{longtable}
3434 \end{centering}
3435
3436 \section{Range List Entries for Non-contiguous Address Ranges}
3437 \label{datarep:noncontiguousaddressranges}
3438 Each entry in a \addtoindex{range list}
3439 (see Section \refersec{chap:noncontiguousaddressranges})
3440 is either a
3441 \addtoindexx{base address selection entry!in range list}
3442 range list entry,
3443 \addtoindexx{range list}
3444 a base address selection entry, or an end-of-list entry.
3445
3446 Each entry begins with an unsigned 1-byte code that indicates the kind of entry
3447 that follows. The encodings for these constants are given in
3448 Table \refersec{tab:rnglistsentryencodingvalues}.
3449
3450 \needlines{10}
3451 \begin{centering}
3452 \setlength{\extrarowheight}{0.1cm}
3453 \begin{longtable}{l|c}
3454   \caption{Range list entry encoding values}
3455   \label{tab:rnglistsentryencodingvalues} \\
3456   \hline \bfseries Range list entry encoding name&\bfseries Value \\ \hline
3457 \endfirsthead
3458   \bfseries Range list entry encoding name&\bfseries Value\\ \hline
3459 \endhead
3460   \hline \emph{Continued on next page}
3461 \endfoot
3462   \hline
3463   \ddag New in \DWARFVersionV
3464 \endlastfoot
3465 \DWRLEendoflist~\ddag    & 0x00 \\
3466 \DWRLEbaseaddressx~\ddag & 0x01 \\
3467 \DWRLEstartxendx~\ddag   & 0x02 \\
3468 \DWRLEstartxlength~\ddag & 0x03 \\
3469 \DWRLEoffsetpair~\ddag   & 0x04 \\
3470 \DWRLEbaseaddress~\ddag  & 0x05 \\
3471 \DWRLEstartend~\ddag     & 0x06 \\
3472 \DWRLEstartlength~\ddag  & 0x07 \\
3473 \end{longtable}
3474 \end{centering}
3475
3476 For a \addtoindex{range list} to be specified, the base address of the
3477 \addtoindexx{base address selection entry!in range list}
3478 corresponding compilation unit must be defined
3479 (see Section \refersec{chap:fullandpartialcompilationunitentries}).
3480
3481 \needlines{6}
3482 \section{String Offsets Table}
3483 \label{chap:stringoffsetstable}
3484 Each set of entries in the string offsets table contained in the
3485 \dotdebugstroffsets{} or \dotdebugstroffsetsdwo{}
3486 section begins with a header containing:
3487 \begin{enumerate}[1. ]
3488 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
3489 \addttindexx{unit\_length}
3490 A 4-byte or 12-byte length containing the length of
3491 the set of entries for this compilation unit, not
3492 including the length field itself. In the 32-bit
3493 DWARF format, this is a 4-byte unsigned integer
3494 (which must be less than \xfffffffzero); in the 64-bit
3495 DWARF format, this consists of the 4-byte value
3496 \wffffffff followed by an 8-byte unsigned integer
3497 that gives the actual length (see
3498 Section \refersec{datarep:32bitand64bitdwarfformats}).
3499
3500 %\needlines{4}
3501 \item  \texttt{version} (\HFTuhalf) \\
3502 \addtoindexx{version number!string offsets table}
3503 A 2-byte version identifier containing the value
3504 \versiondotdebugstroffsets{}.
3505
3506 \item \textit{padding} (\HFTuhalf) \\
3507 Reserved to DWARF (must be zero).
3508 \end{enumerate}
3509
3510 This header is followed by a series of string table offsets
3511 that have the same representation as \DWFORMstrp.
3512 For the 32-bit DWARF format, each offset is 4 bytes long; for
3513 the 64-bit DWARF format, each offset is 8 bytes long.
3514
3515 The \DWATstroffsetsbase{} attribute points to the first
3516 entry following the header. The entries are indexed
3517 sequentially from this base entry, starting from 0.
3518
3519 \section{Address Table}
3520 \label{chap:addresstable}
3521 Each set of entries in the address table contained in the
3522 \dotdebugaddr{} section begins with a header containing:
3523 \begin{enumerate}[1. ]
3524 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
3525 \addttindexx{unit\_length}
3526 A 4-byte or 12-byte length containing the length of
3527 the set of entries for this compilation unit, not
3528 including the length field itself. In the 32-bit
3529 DWARF format, this is a 4-byte unsigned integer
3530 (which must be less than \xfffffffzero); in the 64-bit
3531 DWARF format, this consists of the 4-byte value
3532 \wffffffff followed by an 8-byte unsigned integer
3533 that gives the actual length (see
3534 Section \refersec{datarep:32bitand64bitdwarfformats}).
3535
3536 \needlines{4}
3537 \item  \texttt{version} (\HFTuhalf) \\
3538 \addtoindexx{version number!address table}
3539 A 2-byte version identifier containing the value
3540 \versiondotdebugaddr{}.
3541
3542 \needlines{4}
3543 \item   \texttt{address\_size} (\HFTubyte) \\
3544 A 1-byte unsigned integer containing the size in
3545 bytes of an address (or the offset portion of an
3546 address for segmented addressing) on the target
3547 system.
3548
3549 \needlines{4}
3550 \item   \HFNsegmentselectorsize{} (\HFTubyte) \\
3551 A 1-byte unsigned integer containing the size in
3552 bytes of a segment selector on the target system.
3553 \end{enumerate}
3554
3555 This header is followed by a series of segment/address pairs.
3556 The segment size is given by the \HFNsegmentselectorsize{} field of the
3557 header, and the address size is given by the \addttindex{address\_size}
3558 field of the header. If the \HFNsegmentselectorsize{} field in the header
3559 is zero, the entries consist only of an addresses.
3560
3561 The \DWATaddrbase{} attribute points to the first entry
3562 following the header. The entries are indexed sequentially
3563 from this base entry, starting from 0.
3564
3565 \needlines{10}
3566 \section{Range List Table}
3567 \label{app:ranglisttable}
3568 Each \dotdebugrnglists{} and \dotdebugrnglistsdwo{} section
3569 begins with a header containing:
3570 \begin{enumerate}[1. ]
3571 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
3572 \addttindexx{unit\_length}
3573 A 4-byte or 12-byte length containing the length of
3574 the set of entries for this compilation unit, not
3575 including the length field itself. In the 32-bit
3576 DWARF format, this is a 4-byte unsigned integer
3577 (which must be less than \xfffffffzero); in the 64-bit
3578 DWARF format, this consists of the 4-byte value
3579 \wffffffff followed by an 8-byte unsigned integer
3580 that gives the actual length (see
3581 Section \refersec{datarep:32bitand64bitdwarfformats}).
3582
3583 \needlines{4}
3584 \item  \texttt{version} (\HFTuhalf) \\
3585 \addtoindexx{version number!range list table}
3586 A 2-byte version identifier containing the value
3587 \versiondotdebugrnglists{}.
3588
3589 \needlines{4}
3590 \item   \texttt{address\_size} (\HFTubyte) \\
3591 A 1-byte unsigned integer containing the size in
3592 bytes of an address (or the offset portion of an
3593 address for segmented addressing) on the target
3594 system.
3595
3596 \needlines{4}
3597 \item   \HFNsegmentselectorsize{} (\HFTubyte) \\
3598 A 1-byte unsigned integer containing the size in
3599 bytes of a segment selector on the target system.
3600
3601 \item   \HFNoffsetentrycount{} (\HFTuword) \\
3602 A 4-byte count of the number of offsets
3603 that follow the header.
3604 \bb
3605 This count may be zero.
3606 \eb
3607 \end{enumerate}
3608
3609 Immediately following the header is an array of offsets.
3610 This array is followed by a series of range lists.
3611
3612 \bb
3613 If the \HFNoffsetentrycount{} is non-zero, there
3614 \eb
3615 is one offset for each range list.
3616 The contents
3617 of the $i$\textsuperscript{th} offset is the offset
3618 \bb
3619 (an unsigned integer)
3620 \eb
3621 from the
3622 beginning of the offset array to the location of the
3623 $i$\textsuperscript{th} range list.
3624 \bb
3625 In the 32-bit DWARF format, each offset is 4-bytes in size;
3626 in the 64-bit DWARF format, each offset is 8-bytes in size
3627 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
3628 \eb
3629
3630 \textit{\bb
3631 If the \HFNoffsetentrycount{} is zero, then \DWFORMrnglistx{} cannot
3632 be used to access a range list; \DWFORMsecoffset{} must be used
3633 instead. If the \HFNoffsetentrycount{} is non-zero, then \DWFORMrnglistx{}
3634 may be used to access a range list; this is necessary in split units and
3635 otherwise may be more compact than using \DWFORMsecoffset.
3636 \eb
3637 }
3638
3639 Range lists are
3640 described in Section \refersec{chap:noncontiguousaddressranges}.
3641
3642 \needlines{4}
3643 The segment size is given by the
3644 \HFNsegmentselectorsize{} field of the header, and the address size is
3645 given by the \addttindex{address\_size} field of the header. If the
3646 \HFNsegmentselectorsize{} field in the header is zero, the segment
3647 selector is omitted from the range list entries.
3648
3649 The \DWATrnglistsbase{} attribute points to the first offset
3650 following the header. The range lists are referenced
3651 by the index of the position of their corresponding offset in the
3652 array of offsets, which indirectly specifies the offset to the
3653 target list.
3654
3655 \needlines{12}
3656 \section{Location List Table}
3657 \label{datarep:locationlisttable}
3658 Each \dotdebugloclists{} or \dotdebugloclistsdwo{} section
3659 begins with a header containing:
3660 \begin{enumerate}[1. ]
3661 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
3662 \addttindexx{unit\_length}
3663 A 4-byte or 12-byte length containing the length of
3664 the set of entries for this compilation unit, not
3665 including the length field itself. In the 32-bit
3666 DWARF format, this is a 4-byte unsigned integer
3667 (which must be less than \xfffffffzero); in the 64-bit
3668 DWARF format, this consists of the 4-byte value
3669 \wffffffff followed by an 8-byte unsigned integer
3670 that gives the actual length (see
3671 Section \refersec{datarep:32bitand64bitdwarfformats}).
3672
3673 \needlines{4}
3674 \item  \texttt{version} (\HFTuhalf) \\
3675 \addtoindexx{version number!location list table}
3676 A 2-byte version identifier containing the value
3677 \versiondotdebugloclists{}.
3678
3679 \needlines{5}
3680 \item   \texttt{address\_size} (\HFTubyte) \\
3681 A 1-byte unsigned integer containing the size in
3682 bytes of an address (or the offset portion of an
3683 address for segmented addressing) on the target
3684 system.
3685
3686 \needlines{4}
3687 \item   \HFNsegmentselectorsize{} (\HFTubyte) \\
3688 A 1-byte unsigned integer containing the size in
3689 bytes of a segment selector on the target system.
3690
3691 \item   \HFNoffsetentrycount{} (\HFTuword) \\
3692 A 4-byte count of the number of offsets
3693 that follow the header.
3694 \bb
3695 This count may be zero.
3696 \eb
3697 \end{enumerate}
3698
3699 Immediately following the header is an array of offsets.
3700 This array is followed by a series of location lists.
3701
3702 \bb
3703 If the \HFNoffsetentrycount{} is non-zero, there
3704 \eb
3705 is one offset for each location list. The contents
3706 of the $i$\textsuperscript{th} offset is the offset
3707 \bb
3708 (an unsigned integer)
3709 \eb
3710 from the
3711 beginning of the offset array to the location of the
3712 $i$\textsuperscript{th} location list.
3713 \bb
3714 In the 32-bit DWARF format, each offset is 4-bytes in size;
3715 in the 64-bit DWARF format, each offset is 8-bytes in size
3716 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
3717 \eb
3718
3719 \textit{\bb
3720 If the \HFNoffsetentrycount{} is zero, then \DWFORMloclistx{} cannot
3721 be used to access a location list; \DWFORMsecoffset{} must be used
3722 instead. If the \HFNoffsetentrycount{} is non-zero, then \DWFORMloclistx{}
3723 may be used to access a location list; this is necessary in split units and
3724 otherwise may be more compact than using \DWFORMsecoffset.
3725 \eb
3726 }
3727
3728 Location lists are
3729 described in Section \refersec{chap:locationlists}.
3730
3731 The segment size is given by the
3732 \HFNsegmentselectorsize{} field of the header, and the address size is
3733 given by the \HFNaddresssize{} field of the header. If the
3734 \HFNsegmentselectorsize{} field in the header is zero, the segment
3735 selector is omitted from location list entries.
3736
3737 The \DWATloclistsbase{} attribute points to the first offset
3738 following the header. The location lists are referenced
3739 by the index of the position of their corresponding offset in the
3740 array of offsets, which indirectly specifies the offset to the
3741 target list.
3742
3743 \needlines{6}
3744 \section{Dependencies and Constraints}
3745 \label{datarep:dependenciesandconstraints}
3746 The debugging information in this format is intended to
3747 exist in sections of an object file, or an equivalent
3748 separate file or database, having names beginning with
3749 the prefix ".debug\_" (see Appendix
3750 \refersec{app:dwarfsectionversionnumbersinformative}
3751 for a complete list of such names).
3752 Except as specifically specified, this information is not
3753 aligned on 2-, 4- or 8-byte boundaries. Consequently:
3754
3755 \begin{itemize}
3756 \item For the \thirtytwobitdwarfformat{} and a target architecture with
3757 32-bit addresses, an assembler or compiler must provide a way
3758 to produce 2-byte and 4-byte quantities without alignment
3759 restrictions, and the linker must be able to relocate a
3760 4-byte address or
3761 \addtoindexx{section offset!alignment of}
3762 section offset that occurs at an arbitrary
3763 alignment.
3764
3765 \item For the \thirtytwobitdwarfformat{} and a target architecture with
3766 64-bit addresses, an assembler or compiler must provide a
3767 way to produce 2-byte, 4-byte and 8-byte quantities without
3768 alignment restrictions, and the linker must be able to relocate
3769 an 8-byte address or 4-byte
3770 \addtoindexx{section offset!alignment of}
3771 section offset that occurs at an
3772 arbitrary alignment.
3773
3774 \item For the \sixtyfourbitdwarfformat{} and a target architecture with
3775 32-bit addresses, an assembler or compiler must provide a
3776 way to produce 2-byte, 4-byte and 8-byte quantities without
3777 alignment restrictions, and the linker must be able to relocate
3778 a 4-byte address or 8-byte
3779 \addtoindexx{section offset!alignment of}
3780 section offset that occurs at an
3781 arbitrary alignment.
3782
3783 \textit{It is expected that this will be required only for very large
3784 32-bit programs or by those architectures which support
3785 a mix of 32-bit and 64-bit code and data within the same
3786 executable object.}
3787
3788 \item For the \sixtyfourbitdwarfformat{} and a target architecture with
3789 64-bit addresses, an assembler or compiler must provide a
3790 way to produce 2-byte, 4-byte and 8-byte quantities without
3791 alignment restrictions, and the linker must be able to
3792 relocate an 8-byte address or
3793 \addtoindexx{section offset!alignment of}
3794 section offset that occurs at
3795 an arbitrary alignment.
3796 \end{itemize}
3797
3798 \needlines{10}
3799 \section{Integer Representation Names}
3800 \label{datarep:integerrepresentationnames}
3801 The sizes of the integers used in the lookup by name, lookup
3802 by address, line number, call frame information and other sections
3803 are given in
3804 Table \ref{tab:integerrepresentationnames}.
3805
3806 \needlines{12}
3807 \begin{centering}
3808 \setlength{\extrarowheight}{0.1cm}
3809 \begin{longtable}{c|l}
3810   \caption{Integer representation names} \label{tab:integerrepresentationnames}\\
3811   \hline \bfseries Representation name&\bfseries Representation \\ \hline
3812 \endfirsthead
3813   \bfseries Representation name&\bfseries Representation\\ \hline
3814 \endhead
3815   \hline \emph{Continued on next page}
3816 \endfoot
3817   \hline
3818 \endlastfoot
3819
3820 \HFTsbyte&  signed, 1-byte integer \\
3821 \HFTubyte&unsigned, 1-byte integer \\
3822 \HFTuhalf&unsigned, 2-byte integer \\
3823 \HFTuword&unsigned, 4-byte integer \\
3824
3825 \end{longtable}
3826 \end{centering}
3827
3828 \needlines{6}
3829 \section{Type Signature Computation}
3830 \label{datarep:typesignaturecomputation}
3831
3832 A \addtoindex{type signature} is used by a DWARF consumer
3833 to resolve type references to the type definitions that
3834 are contained in \addtoindex{type unit}s (see Section
3835 \refersec{chap:typeunitentries}).
3836
3837 \textit{A type signature is computed only by a DWARF producer;
3838 \addtoindexx{type signature!computation} a consumer need
3839 only compare two type signatures to check for equality.}
3840
3841 \needlines{4}
3842 The type signature for a type T0 is formed from the
3843 \MDfive{}\footnote{\livetarg{def:MDfive}{MD5} Message Digest Algorithm,
3844 R.L. Rivest, RFC 1321, April 1992}
3845 digest of a flattened description of the type. The flattened
3846 description of the type is a byte sequence derived from the
3847 DWARF encoding of the type as follows:
3848 \begin{enumerate}[1. ]
3849
3850 \item Start with an empty sequence S and a list V of visited
3851 types, where V is initialized to a list containing the type
3852 T0 as its single element. Elements in V are indexed from 1,
3853 so that V[1] is T0.
3854
3855 \item If the debugging information entry represents a type that
3856 is nested inside another type or a namespace, append to S
3857 the type\textquoteright s context as follows: For each surrounding type
3858 or namespace, beginning with the outermost such construct,
3859 append the letter 'C', the DWARF tag of the construct, and
3860 the name (taken from
3861 \addtoindexx{name attribute}
3862 the \DWATname{} attribute) of the type
3863 \addtoindexx{name attribute}
3864 or namespace (including its trailing null byte).
3865
3866 \item  Append to S the letter 'D', followed by the DWARF tag of
3867 the debugging information entry.
3868
3869 \item For each of the attributes in
3870 Table \refersec{tab:attributesusedintypesignaturecomputation}
3871 that are present in
3872 the debugging information entry, in the order listed,
3873 append to S a marker letter (see below), the DWARF attribute
3874 code, and the attribute value.
3875
3876 \begin{table}[ht]
3877 \caption{Attributes used in type signature computation}
3878 \label{tab:attributesusedintypesignaturecomputation}
3879 \simplerule[\textwidth]
3880 \begin{center}
3881 \autocols[0pt]{c}{2}{l}{
3882 \DWATname,
3883 \DWATaccessibility,
3884 \DWATaddressclass,
3885 \DWATalignment,
3886 \DWATallocated,
3887 \DWATartificial,
3888 \DWATassociated,
3889 \DWATbinaryscale,
3890 %\DWATbitoffset,
3891 \DWATbitsize,
3892 \DWATbitstride,
3893 \DWATbytesize,
3894 \DWATbytestride,
3895 \DWATconstexpr,
3896 \DWATconstvalue,
3897 \DWATcontainingtype,
3898 \DWATcount,
3899 \DWATdatabitoffset,
3900 \DWATdatalocation,
3901 \DWATdatamemberlocation,
3902 \DWATdecimalscale,
3903 \DWATdecimalsign,
3904 \DWATdefaultvalue,
3905 \DWATdigitcount,
3906 \DWATdiscr,
3907 \DWATdiscrlist,
3908 \DWATdiscrvalue,
3909 \DWATencoding,
3910 \DWATendianity,
3911 \DWATenumclass,
3912 \DWATexplicit,
3913 \DWATisoptional,
3914 \DWATlocation,
3915 \DWATlowerbound,
3916 \DWATmutable,
3917 \DWATordering,
3918 \DWATpicturestring,
3919 \DWATprototyped,
3920 \DWATrank,
3921 \DWATreference,
3922 \DWATrvaluereference,
3923 \DWATsmall,
3924 \DWATsegment,
3925 \DWATstringlength,
3926 \DWATstringlengthbitsize,
3927 \DWATstringlengthbytesize,
3928 \DWATthreadsscaled,
3929 \DWATupperbound,
3930 \DWATuselocation,
3931 \DWATuseUTFeight,
3932 \DWATvariableparameter,
3933 \DWATvirtuality,
3934 \DWATvisibility,
3935 \DWATvtableelemlocation
3936 }
3937 \end{center}
3938 \simplerule[\textwidth]
3939 \end{table}
3940
3941 Note that except for the initial
3942 \DWATname{} attribute,
3943 \addtoindexx{name attribute}
3944 attributes are appended in order according to the alphabetical
3945 spelling of their identifier.
3946
3947 \needlines{4}
3948 If an implementation defines any vendor-specific attributes,
3949 any such attributes that are essential to the definition of
3950 the type are also included at the end of the above list,
3951 in their own alphabetical suborder.
3952
3953 An attribute that refers to another type entry T is processed
3954 as follows:
3955 \begin{enumerate}[ a)]
3956 \item
3957 If T is in the list V at some V[x], use the
3958 letter 'R' as the marker and use the unsigned LEB128\addtoindexx{LEB128!unsigned}
3959 encoding of x as the attribute value.
3960
3961 \item
3962 Otherwise, append type T to the list V, then
3963 use the letter 'T'
3964 as the marker, process the type T recursively by performing
3965 Steps 2 through 7, and use the result as the attribute value.
3966 \end{enumerate}
3967
3968 \needlines{4}
3969 Other attribute values use the letter 'A' as the marker, and
3970 the value consists of the form code (encoded as an unsigned
3971 LEB128 value) followed by the encoding of the value according
3972 to the form code. To ensure reproducibility of the signature,
3973 the set of forms used in the signature computation is limited
3974 to the following:
3975 \DWFORMsdata,
3976 \DWFORMflag,
3977 \DWFORMstring,
3978 \DWFORMexprloc,
3979 and \DWFORMblock.
3980
3981 \item If the tag in Step 3 is one of \DWTAGpointertype,
3982 \DWTAGreferencetype,
3983 \DWTAGrvaluereferencetype,
3984 \DWTAGptrtomembertype,
3985 or \DWTAGfriend, and the referenced
3986 type (via the \DWATtype{} or
3987 \DWATfriend{} attribute) has a
3988 \DWATname{} attribute, append to S the letter 'N', the DWARF
3989 attribute code (\DWATtype{} or
3990 \DWATfriend), the context of
3991 the type (according to the method in Step 2), the letter 'E',
3992 and the name of the type. For \DWTAGfriend, if the referenced
3993 entry is a \DWTAGsubprogram, the context is omitted and the
3994 name to be used is the ABI-specific name of the subprogram
3995 (for example, the mangled linker name).
3996
3997 \needlines{6}
3998 \item If the tag in Step 3 is not one of \DWTAGpointertype,
3999 \DWTAGreferencetype,
4000 \DWTAGrvaluereferencetype,
4001 \DWTAGptrtomembertype, or
4002 \DWTAGfriend, but has
4003 a \DWATtype{} attribute, or if the referenced type (via
4004 the \DWATtype{} or
4005 \DWATfriend{} attribute) does not have a
4006 \DWATname{} attribute, the attribute is processed according to
4007 the method in Step 4 for an attribute that refers to another
4008 type entry.
4009
4010
4011 \item Visit each child C of the debugging information
4012 entry as follows: If C is a nested type entry or a member
4013 function entry, and has
4014 a \DWATname{} attribute, append to
4015 \addtoindexx{name attribute}
4016 S the letter 'S', the tag of C, and its name; otherwise,
4017 process C recursively by performing Steps 3 through 7,
4018 appending the result to S. Following the last child (or if
4019 there are no children), append a zero byte.
4020 \end{enumerate}
4021
4022
4023
4024 For the purposes of this algorithm, if a debugging information
4025 entry S has a
4026 \DWATspecification{}
4027 attribute that refers to
4028 another entry D (which has a
4029 \DWATdeclaration{}
4030 attribute),
4031 then S inherits the attributes and children of D, and S is
4032 processed as if those attributes and children were present in
4033 the entry S. Exception: if a particular attribute is found in
4034 both S and D, the attribute in S is used and the corresponding
4035 one in D is ignored.
4036
4037 \needlines{4}
4038 DWARF tag and attribute codes are appended to the sequence
4039 as unsigned LEB128\addtoindexx{LEB128!unsigned} values,
4040 using the values defined earlier in this chapter.
4041
4042 \textit{A grammar describing this computation may be found in
4043 Appendix \refersec{app:typesignaturecomputationgrammar}.
4044 }
4045
4046 \textit{An attribute that refers to another type entry is
4047 recursively processed or replaced with the name of the
4048 referent (in Step 4, 5 or 6). If neither treatment applies to
4049 an attribute that references another type entry, the entry
4050 that contains that attribute is not suitable for a
4051 separate \addtoindex{type unit}.}
4052
4053 \textit{If a debugging information entry contains an attribute from
4054 the list above that would require an unsupported form, that
4055 entry is not suitable for a separate
4056 \addtoindex{type unit}.}
4057
4058 \textit{A type is suitable for a separate
4059 \addtoindex{type unit} only
4060 if all of the type entries that it contains or refers to in
4061 Steps 6 and 7 are themselves suitable for a separate
4062 \addtoindex{type unit}.}
4063
4064 \needlines{4}
4065 \textit{Where the DWARF producer may reasonably choose two or
4066 more different forms for a given attribute, it should choose
4067 the simplest possible form in computing the signature. (For
4068 example, a constant value should be preferred to a location
4069 expression when possible.)}
4070
4071 Once the string S has been formed from the DWARF encoding,
4072 an 16-byte \MDfive{} digest is computed for the string and the
4073 last eight bytes are taken as the type signature.
4074
4075 \textit{The string S is intended to be a flattened representation of
4076 the type that uniquely identifies that type (that is, a different
4077 type is highly unlikely to produce the same string).}
4078
4079 \needlines{6}
4080 \textit{A debugging information entry is not be placed in a
4081 separate \addtoindex{type unit}
4082 if any of the following apply:}
4083
4084 \begin{itemize}
4085
4086 \item \textit{The entry has an attribute whose value is a location
4087 description, and the location description
4088 contains a reference to
4089 another debugging information entry (for example, a \DWOPcallref{}
4090 operator), as it is unlikely that the entry will remain
4091 identical across compilation units.}
4092
4093 \item \textit{The entry has an attribute whose value refers
4094 to a code location or a \addtoindex{location list}.}
4095
4096 \item \textit{The entry has an attribute whose value refers
4097 to another debugging information entry that does not represent
4098 a type.}
4099 \end{itemize}
4100
4101
4102 \needlines{4}
4103 \textit{Certain attributes are not included in the type signature:}
4104
4105 \begin{itemize}
4106 \item \textit{The \DWATdeclaration{} attribute is not included because it
4107 indicates that the debugging information entry represents an
4108 incomplete declaration, and incomplete declarations should
4109 not be placed in
4110 \addtoindexx{type unit}
4111 separate type units.}
4112
4113 \item \textit{The \DWATdescription{} attribute is not included because
4114 it does not provide any information unique to the defining
4115 declaration of the type.}
4116
4117 \item \textit{The \DWATdeclfile,
4118 \DWATdeclline, and
4119 \DWATdeclcolumn{} attributes are not included because they
4120 may vary from one source file to the next, and would prevent
4121 two otherwise identical type declarations from producing the
4122 same \MDfive{} digest.}
4123
4124 \item \textit{The \DWATobjectpointer{} attribute is not included
4125 because the information it provides is not necessary for the
4126 computation of a unique type signature.}
4127
4128 \end{itemize}
4129
4130 \textit{Nested types and some types referred to by a debugging
4131 information entry are encoded by name rather than by recursively
4132 encoding the type to allow for cases where a complete definition
4133 of the type might not be available in all compilation units.}
4134
4135 %\needlines{4}
4136 \textit{If a type definition contains the definition of a member function,
4137 it cannot be moved as is into a type unit, because the member function
4138 contains attributes that are unique to that compilation unit.
4139 Such a type definition can be moved to a type unit by rewriting the
4140 debugging information entry tree,
4141 moving the member function declaration into a separate declaration tree,
4142 and replacing the function definition in the type with a non-defining
4143 declaration of the function (as if the function had been defined out of
4144 line).}
4145
4146 An example that illustrates the computation of an \MDfive{} digest may be found in
4147 Appendix \refersec{app:usingtypeunits}.
4148
4149 \section{Name Table Hash Function}
4150 \label{datarep:nametablehashfunction}
4151 The hash function used for hashing name strings in the accelerated
4152 access name index table (see Section \refersec{chap:acceleratedaccess})
4153 is defined in \addtoindex{C} as shown in
4154 Figure \referfol{fig:nametablehashfunctiondefinition}.\footnoteRR{
4155 This hash function is sometimes known as the
4156 "\addtoindex{Bernstein hash function}" or the
4157 "\addtoindex{DJB hash function}"
4158 (see, for example,
4159 \hrefself{http://en.wikipedia.org/wiki/List\_of\_hash\_functions} or
4160 \hrefself{http://stackoverflow.com/questions/10696223/reason-for-5381-number-in-djb-hash-function)}.}
4161
4162 \begin{figure}[ht]
4163 \begin{nlnlisting}
4164
4165 uint32_t /* must be a 32-bit integer type */
4166     hash(unsigned char *str)
4167     {
4168         uint32_t hash = 5381;
4169         int c;
4170
4171         while (c = *str++)
4172             hash = hash * 33 + c;
4173
4174         return hash;
4175     }
4176
4177 \end{nlnlisting}
4178 \caption{Name Table Hash Function Definition}
4179 \label{fig:nametablehashfunctiondefinition}
4180 \end{figure}
4181