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