1 \chapter{Data Representation}
2 \label{datarep:datarepresentation}
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.
9 \section{Vendor Extensibility}
10 \label{datarep:vendorextensibility}
11 \addtoindexx{vendor extensibility}
12 \addtoindexx{vendor specific extensions|see{vendor extensibility}}
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.
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
26 (\DWTAGlouserMARK\DWTAGhiuserMARK{} DW\_TAG,
27 \DWATlouserMARK\DWAThiuserMARK{} DW\_AT,
28 \DWENDlouserMARK\DWENDhiuserMARK{} DW\_END,
29 \DWATElouserMARK\DWATEhiuserMARK{} DW\_ATE,
30 \DWOPlouserMARK\DWOPhiuserMARK{} DW\_OP,
31 \DWLANGlouserMARK\DWLANGhiuserMARK{}DW\_LANG,
32 \DWLNElouserMARK\DWLNEhiuserMARK{} DW\_LNE,
33 \DWCClouserMARK\DWCChiuserMARK{} DW\_CC or
34 \DWCFAlouserMARK\DWCFAhiuserMARK{} DW\_CFA
35 respectively) followed by
36 \_lo\_user or \_hi\_user.
37 \textit{For example, for entry tags, the special
38 labels are \DWTAGlouserNAME{} and \DWTAGhiuserNAME.}
39 Values in the range between \textit{prefix}\_lo\_user
40 and \textit{prefix}\_hi\_user inclusive,
41 are reserved for vendor specific extensions. Vendors may
42 use values in this range without conflicting with current or
43 future system\dash defined values. All other values are reserved
44 for use by the system.
46 \textit{There may also be codes for vendor specific extensions
47 between the number of standard line number opcodes and
48 the first special line number opcode. However, since the
49 number of standard opcodes varies with the DWARF version,
50 the range for extensions is also version dependent. Thus,
51 \DWLNSlouserTARG{} and
52 \DWLNShiuserTARG{} symbols are not defined.
55 Vendor defined tags, attributes, base type encodings, location
56 atoms, language names, line number actions, calling conventions
57 and call frame instructions, conventionally use the form
58 \text{prefix\_vendor\_id\_name}, where
59 \textit{vendor\_id}\addtoindexx{vendor id} is some identifying
60 character sequence chosen so as to avoid conflicts with
63 To ensure that extensions added by one vendor may be safely
64 ignored by consumers that do not understand those extensions,
65 the following rules should be followed:
66 \begin{enumerate}[1. ]
68 \item New attributes should be added in such a way that a
69 debugger may recognize the format of a new attribute value
70 without knowing the content of that attribute value.
72 \item The semantics of any new attributes should not alter
73 the semantics of previously existing attributes.
75 \item The semantics of any new tags should not conflict with
76 the semantics of previously existing tags.
78 \item Do not add any new forms of attribute value.
83 \section{Reserved Values}
84 \label{datarep:reservedvalues}
85 \subsection{Error Values}
86 \label{datarep:errorvalues}
87 \addtoindexx{reserved values!error}
90 \addtoindexx{error value}
91 a convenience for consumers of DWARF information, the value
92 0 is reserved in the encodings for attribute names, attribute
93 forms, base type encodings, location operations, languages,
94 line number program opcodes, macro information entries and tag
95 names to represent an error condition or unknown value. DWARF
96 does not specify names for these reserved values, since they
97 do not represent valid encodings for the given type and should
98 not appear in DWARF debugging information.
101 \subsection{Initial Length Values}
102 \label{datarep:initiallengthvalues}
103 \addtoindexx{reserved values!initial length}
105 An \livetarg{datarep:initiallengthvalues}{initial length field} is one of the length fields that occur
107 of those DWARF sections that
113 \dotdebugpubnames{}, and
114 \dotdebugpubtypes{}) or the length field
115 that occurs at the beginning of the CIE and FDE structures
116 in the \dotdebugframe{} section.
118 In an \addtoindex{initial length field}, the values \wfffffffzero through
119 \wffffffff are reserved by DWARF to indicate some form of
120 extension relative to \addtoindex{DWARF Version 2}; such values must not
121 be interpreted as a length field. The use of one such value,
122 \xffffffff, is defined below
123 (see Section \refersec{datarep:32bitand64bitdwarfformats});
125 the other values is reserved for possible future extensions.
129 \section{Executable Objects and Shared Objects}
130 \label{datarep:executableobjectsandsharedobjects}
132 The relocated addresses in the debugging information for an
133 executable object are virtual addresses and the relocated
134 addresses in the debugging information for a shared object
135 are offsets relative to the start of the lowest region of
136 memory loaded from that shared object.
138 \textit{This requirement makes the debugging information for
139 shared objects position independent. Virtual addresses in a
140 shared object may be calculated by adding the offset to the
141 base address at which the object was attached. This offset
142 is available in the run\dash time linker\textquoteright s data structures.}
146 \section{32-Bit and 64-Bit DWARF Formats}
147 \label{datarep:32bitand64bitdwarfformats}
148 \hypertarget{datarep:xxbitdwffmt}{}
149 \addtoindexx{32-bit DWARF format}
150 \addtoindexx{64-bit DWARF format}
151 There are two closely related file formats. In the 32\dash bit DWARF
152 format, all values that represent lengths of DWARF sections
153 and offsets relative to the beginning of DWARF sections are
154 represented using 32\dash bits. In the 64\dash bit DWARF format, all
155 values that represent lengths of DWARF sections and offsets
156 relative to the beginning of DWARF sections are represented
157 using 64\dash bits. A special convention applies to the initial
158 length field of certain DWARF sections, as well as the CIE and
159 FDE structures, so that the 32\dash bit and 64\dash bit DWARF formats
160 can coexist and be distinguished within a single linked object.
162 The differences between the 32\dash\ and 64\dash bit
164 detailed in the following:
165 \begin{enumerate}[1. ]
167 \item In the 32\dash bit DWARF format, an
168 \addtoindex{initial length field}
170 \addtoindexx{initial length field!encoding}
171 Section \refersec{datarep:initiallengthvalues})
172 is an unsigned 32\dash bit integer (which
173 must be less than \xfffffffzero); in the 64\dash bit DWARF format,
174 an \addtoindex{initial length field} is 96 bits in size,
177 \item The first 32\dash bits have the value \xffffffff.
179 \item The following 64\dash bits contain the actual length
180 represented as an unsigned 64\dash bit integer.
183 \textit{This representation allows a DWARF consumer to dynamically
184 detect that a DWARF section contribution is using the 64\dash bit
185 format and to adapt its processing accordingly.}
187 \item Section offset and section length
188 \hypertarget{datarep:sectionoffsetlength}{}
189 \addtoindexx{section length!use in headers}
191 \addtoindexx{section offset!use in headers}
192 in the headers of DWARF sections (other
193 \addtoindexx{initial length field}
195 \addtoindex{initial length}
196 fields) are listed following. In the 32\dash bit DWARF format these
197 are 32\dash bit unsigned integer values; in the 64\dash bit DWARF format,
199 \addtoindexx{section length!in .debug\_aranges header}
201 \addtoindexx{section length!in .debug\_pubnames header}
203 \addtoindexx{section length!in .debug\_pubtypes header}
204 unsigned integer values.
208 Section &Name & Role \\ \hline
209 \dotdebugaranges{} & \addtoindex{debug\_info\_offset} & offset in \dotdebuginfo{} \\
210 \dotdebugframe{}/CIE & \addtoindex{CIE\_id} & CIE distinguished value \\
211 \dotdebugframe{}/FDE & \addtoindex{CIE\_pointer} & offset in \dotdebugframe{} \\
212 \dotdebuginfo{} & \addtoindex{debug\_abbrev\_offset} & offset in \dotdebugabbrev{} \\
213 \dotdebugline{} & \addtoindex{header\_length} & length of header itself \\
214 \dotdebugpubnames{} & \addtoindex{debug\_info\_offset} & offset in \dotdebuginfo{} \\
215 & \addtoindex{debug\_info\_length} & length of \dotdebuginfo{} \\
217 \dotdebugpubtypes{} & \addtoindex{debug\_info\_offset} & offset in \dotdebuginfo{} \\
218 & \addtoindex{debug\_info\_length} & length of \dotdebuginfo{} \\
220 \dotdebugtypes{} & \addtoindex{debug\_abbrev\_offset} & offset in \dotdebugabbrev{} \\
221 & \addtoindex{type\_offset} & offset in \dotdebugtypes{} \\
226 The \texttt{CIE\_id} field in a CIE structure must be 64 bits because
227 it overlays the \texttt{CIE\_pointer} in a FDE structure; this implicit
228 union must be accessed to distinguish whether a CIE or FDE is
229 present, consequently, these two fields must exactly overlay
230 each other (both offset and size).
232 \item Within the body of the \dotdebuginfo{} or \dotdebugtypes{}
233 section, certain forms of attribute value depend on the choice
234 of DWARF format as follows. For the 32\dash bit DWARF format,
235 the value is a 32\dash bit unsigned integer; for the 64\dash bit DWARF
236 format, the value is a 64\dash bit unsigned integer.
239 Form & Role \\ \hline
240 \DWFORMrefaddr& offset in \dotdebuginfo{} \\
241 \DWFORMsecoffset& offset in a section other than \\
242 &\dotdebuginfo{} or \dotdebugstr{} \\
243 \DWFORMstrp&offset in \dotdebugstr{} \\
244 \DWOPcallref&offset in \dotdebuginfo{} \\
248 \item Within the body of the \dotdebugpubnames{} and
250 sections, the representation of the first field
251 of each tuple (which represents an offset in the
253 section) depends on the DWARF format as follows: in the
254 32\dash bit DWARF format, this field is a 32\dash bit unsigned integer;
255 in the 64\dash bit DWARF format, it is a 64\dash bit unsigned integer.
260 The 32\dash bit and 64\dash bit DWARF format conventions must \emph{not} be
261 intermixed within a single compilation unit.
263 \textit{Attribute values and section header fields that represent
264 addresses in the target program are not affected by these
267 A DWARF consumer that supports the 64\dash bit DWARF format must
268 support executables in which some compilation units use the
269 32\dash bit format and others use the 64\dash bit format provided that
270 the combination links correctly (that is, provided that there
271 are no link\dash time errors due to truncation or overflow). (An
272 implementation is not required to guarantee detection and
273 reporting of all such errors.)
275 \textit{It is expected that DWARF producing compilers will \emph{not} use
276 the 64\dash bit format \emph{by default}. In most cases, the division of
277 even very large applications into a number of executable and
278 shared objects will suffice to assure that the DWARF sections
279 within each individual linked object are less than 4 GBytes
280 in size. However, for those cases where needed, the 64\dash bit
281 format allows the unusual case to be handled as well. Even
282 in this case, it is expected that only application supplied
283 objects will need to be compiled using the 64\dash bit format;
284 separate 32\dash bit format versions of system supplied shared
285 executable libraries can still be used.}
289 \section{Format of Debugging Information}
290 \label{datarep:formatofdebugginginformation}
292 For each compilation unit compiled with a DWARF producer,
293 a contribution is made to the \dotdebuginfo{} section of
294 the object file. Each such contribution consists of a
295 compilation unit header
296 (see Section \refersec{datarep:compilationunitheader})
298 single \DWTAGcompileunit{} or
299 \DWTAGpartialunit{} debugging
300 information entry, together with its children.
302 For each type defined in a compilation unit, a contribution may
303 be made to the \dotdebugtypes{}
304 section of the object file. Each
305 such contribution consists of a
306 \addtoindex{type unit} header
307 (see Section \refersec{datarep:typeunitheader})
308 followed by a \DWTAGtypeunit{} entry, together with
311 Each debugging information entry begins with a code that
312 represents an entry in a separate
313 \addtoindex{abbreviations table}. This
314 code is followed directly by a series of attribute values.
316 The appropriate entry in the
317 \addtoindex{abbreviations table} guides the
318 interpretation of the information contained directly in the
320 \dotdebugtypes{} section.
323 Multiple debugging information entries may share the same
324 abbreviation table entry. Each compilation unit is associated
325 with a particular abbreviation table, but multiple compilation
326 units may share the same table.
327 \subsection{Unit Headers}
328 \label{datarep:unitheaders}
330 \subsubsection{Compilation Unit Header}
331 \label{datarep:compilationunitheader}
332 \begin{enumerate}[1. ]
334 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
335 \addttindexx{unit\_length}
336 A 4\dash byte or 12\dash byte
337 \addtoindexx{initial length}
338 unsigned integer representing the length
339 of the \dotdebuginfo{}
340 contribution for that compilation unit,
341 not including the length field itself. In the \thirtytwobitdwarfformat,
342 this is a 4\dash byte unsigned integer (which must be less
343 than \xfffffffzero); in the \sixtyfourbitdwarfformat, this consists
344 of the 4\dash byte value \wffffffff followed by an 8\dash byte unsigned
345 integer that gives the actual length
346 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
349 \item \texttt{version} (\addtoindex{uhalf}) \\
350 A 2\dash byte unsigned integer representing the version of the
351 DWARF information for the compilation unit \addtoindexx{version number!compilation unit}
352 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
353 The value in this field is 4.
355 \item \addttindex{debug\_abbrev\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
357 \addtoindexx{section offset!in .debug\_info header}
358 4\dash byte or 8\dash byte unsigned offset into the
360 section. This offset associates the compilation unit with a
361 particular set of debugging information entry abbreviations. In
362 the \thirtytwobitdwarfformat, this is a 4\dash byte unsigned length;
363 in the \sixtyfourbitdwarfformat, this is an 8\dash byte unsigned length
364 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
366 \item \texttt{address\_size} (\addtoindex{ubyte}) \\
367 A 1\dash byte unsigned integer representing the size in bytes of
368 \addttindexx{address\_size}
369 an address on the target architecture. If the system uses
370 \addtoindexx{address space!segmented}
371 segmented addressing, this value represents the size of the
372 offset portion of an address.
377 \subsubsection{Type Unit Header}
378 \label{datarep:typeunitheader}
380 The header for the series of debugging information entries
381 contributing to the description of a type that has been
382 placed in its own \addtoindex{type unit}, within the
383 \dotdebugtypes{} section,
384 consists of the following information:
385 \begin{enumerate}[1. ]
387 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
388 \addttindexx{unit\_length}
389 A 4\dash byte or 12\dash byte unsigned integer
390 \addtoindexx{initial length}
391 representing the length
392 of the \dotdebugtypes{} contribution for that type unit,
393 not including the length field itself. In the \thirtytwobitdwarfformat,
394 this is a 4\dash byte unsigned integer (which must be
395 less than \xfffffffzero); in the \sixtyfourbitdwarfformat, this
396 consists of the 4\dash byte value \wffffffff followed by an
397 8\dash byte unsigned integer that gives the actual length
398 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
401 \item \texttt{version} (\addtoindex{uhalf}) \\
402 A 2\dash byte unsigned integer representing the version of the
403 DWARF information for the
404 type unit\addtoindexx{version number!type unit}
405 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
406 The value in this field is 4.
408 \item \addttindex{debug\_abbrev\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
410 \addtoindexx{section offset!in .debug\_types header}
411 4\dash byte or 8\dash byte unsigned offset into the
413 section. This offset associates the type unit with a
414 particular set of debugging information entry abbreviations. In
415 the \thirtytwobitdwarfformat, this is a 4\dash byte unsigned length;
416 in the \sixtyfourbitdwarfformat, this is an 8\dash byte unsigned length
417 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
419 \item \texttt{address\_size} (ubyte) \\
420 A 1\dash byte unsigned integer representing the size
421 \addtoindexx{size of an address}
423 \addttindexx{address\_size}
424 an address on the target architecture. If the system uses
425 \addtoindexx{address space!segmented}
426 segmented addressing, this value represents the size of the
427 offset portion of an address.
429 \item \texttt{type\_signature} (8\dash byte unsigned integer) \\
430 \addtoindexx{type signature}
432 \addttindexx{type\_signature}
433 64\dash bit unique signature (see Section
434 \refersec{datarep:typesignaturecomputation})
435 of the type described in this type
438 \textit{An attribute that refers (using
439 \DWFORMrefsigeight{}) to
440 the primary type contained in this
441 \addtoindex{type unit} uses this value.}
443 \item \texttt{type\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
444 \addttindexx{type\_offset}
445 A 4\dash byte or 8\dash byte unsigned offset
446 \addtoindexx{section offset!in .debug\_types header}
447 relative to the beginning
448 of the \addtoindex{type unit} header.
449 This offset refers to the debugging
450 information entry that describes the type. Because the type
451 may be nested inside a namespace or other structures, and may
452 contain references to other types that have not been placed in
453 separate type units, it is not necessarily either the first or
454 the only entry in the type unit. In the \thirtytwobitdwarfformat,
455 this is a 4\dash byte unsigned length; in the \sixtyfourbitdwarfformat,
456 this is an 8\dash byte unsigned length
457 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
461 \subsection{Debugging Information Entry}
462 \label{datarep:debugginginformationentry}
464 Each debugging information entry begins with an unsigned LEB128
465 number containing the abbreviation code for the entry. This
466 code represents an entry within the abbreviations table
467 associated with the compilation unit containing this entry. The
468 abbreviation code is followed by a series of attribute values.
470 On some architectures, there are alignment constraints on
471 section boundaries. To make it easier to pad debugging
472 information sections to satisfy such constraints, the
473 abbreviation code 0 is reserved. Debugging information entries
474 consisting of only the abbreviation code 0 are considered
477 \subsection{Abbreviations Tables}
478 \label{datarep:abbreviationstables}
480 The abbreviations tables for all compilation units
481 are contained in a separate object file section called
483 As mentioned before, multiple compilation
484 units may share the same abbreviations table.
486 The abbreviations table for a single compilation unit consists
487 of a series of abbreviation declarations. Each declaration
488 specifies the tag and attributes for a particular form of
489 debugging information entry. Each declaration begins with
490 an unsigned LEB128 number representing the abbreviation
491 code itself. It is this code that appears at the beginning
492 of a debugging information entry in the
495 section. As described above, the abbreviation
496 code 0 is reserved for null debugging information entries. The
497 abbreviation code is followed by another unsigned LEB128
498 number that encodes the entry\textquoteright s tag. The encodings for the
499 tag names are given in
500 Table \refersec{tab:tagencodings}.
503 \setlength{\extrarowheight}{0.1cm}
504 \begin{longtable}{l|l}
506 \caption{Tag encodings} \label{tab:tagencodings} \\
507 \hline \bfseries Tag name&\bfseries Value\\ \hline
509 \bfseries Tag name&\bfseries Value \\ \hline
511 \hline \emph{Continued on next page}
515 \DWTAGarraytype{} &0x01 \\
516 \DWTAGclasstype&0x02 \\
517 \DWTAGentrypoint&0x03 \\
518 \DWTAGenumerationtype&0x04 \\
519 \DWTAGformalparameter&0x05 \\
520 \DWTAGimporteddeclaration&0x08 \\
522 \DWTAGlexicalblock&0x0b \\
524 \DWTAGpointertype&0x0f \\
525 \DWTAGreferencetype&0x10 \\
526 \DWTAGcompileunit&0x11 \\
527 \DWTAGstringtype&0x12 \\
528 \DWTAGstructuretype&0x13 \\
529 \DWTAGsubroutinetype&0x15 \\
530 \DWTAGtypedef&0x16 \\
531 \DWTAGuniontype&0x17 \\
532 \DWTAGunspecifiedparameters&0x18 \\
533 \DWTAGvariant&0x19 \\
534 \DWTAGcommonblock&0x1a \\
535 \DWTAGcommoninclusion&0x1b \\
536 \DWTAGinheritance&0x1c \\
537 \DWTAGinlinedsubroutine&0x1d \\
539 \DWTAGptrtomembertype&0x1f \\
540 \DWTAGsettype&0x20 \\
541 \DWTAGsubrangetype&0x21 \\
542 \DWTAGwithstmt&0x22 \\
543 \DWTAGaccessdeclaration&0x23 \\
544 \DWTAGbasetype&0x24 \\
545 \DWTAGcatchblock&0x25 \\
546 \DWTAGconsttype&0x26 \\
547 \DWTAGconstant&0x27 \\
548 \DWTAGenumerator&0x28 \\
549 \DWTAGfiletype&0x29 \\
551 \DWTAGnamelist&0x2b \\
552 \DWTAGnamelistitem&0x2c \\
553 \DWTAGpackedtype&0x2d \\
554 \DWTAGsubprogram&0x2e \\
555 \DWTAGtemplatetypeparameter&0x2f \\
556 \DWTAGtemplatevalueparameter&0x30 \\
557 \DWTAGthrowntype&0x31 \\
558 \DWTAGtryblock&0x32 \\
559 \DWTAGvariantpart&0x33 \\
560 \DWTAGvariable&0x34 \\
561 \DWTAGvolatiletype&0x35 \\
562 \DWTAGdwarfprocedure&0x36 \\
563 \DWTAGrestricttype&0x37 \\
564 \DWTAGinterfacetype&0x38 \\
565 \DWTAGnamespace&0x39 \\
566 \DWTAGimportedmodule&0x3a \\
567 \DWTAGunspecifiedtype&0x3b \\
568 \DWTAGpartialunit&0x3c \\
569 \DWTAGimportedunit&0x3d \\
570 \DWTAGcondition&\xiiif \\
571 \DWTAGsharedtype&0x40 \\
572 \DWTAGtypeunit{} &0x41 \\
573 \DWTAGrvaluereferencetype{} &0x42 \\
574 \DWTAGtemplatealias{} &0x43 \\
575 \DWTAGcoarraytype &0x44 \\
576 \DWTAGgenericsubrange &0x45 \\
577 \DWTAGlouser&0x4080 \\
578 \DWTAGhiuser&\xffff \\
582 Following the tag encoding is a 1\dash byte value that determines
583 whether a debugging information entry using this abbreviation
584 has child entries or not. If the value is
586 the next physically succeeding entry of any debugging
587 information entry using this abbreviation is the first
588 child of that entry. If the 1\dash byte value following the
589 abbreviation\textquoteright s tag encoding is
590 \DWCHILDRENnoTARG, the next
591 physically succeeding entry of any debugging information entry
592 using this abbreviation is a sibling of that entry. (Either
593 the first child or sibling entries may be null entries). The
594 encodings for the child determination byte are given in
595 Table \refersec{tab:childdeterminationencodings}
597 Section \refersec{chap:relationshipofdebugginginformationentries},
598 each chain of sibling entries is terminated by a null entry.)
602 \setlength{\extrarowheight}{0.1cm}
603 \begin{longtable}{l|l}
604 \caption{Child determination encodings}
605 \label{tab:childdeterminationencodings}
606 \addtoindexx{Child determination encodings} \\
607 \hline \bfseries Children determination name&\bfseries Value \\ \hline
609 \bfseries Children determination name&\bfseries Value \\ \hline
611 \hline \emph{Continued on next page}
615 \DWCHILDRENno&0x00 \\
616 \DWCHILDRENyes&0x01 \\ \hline
621 Finally, the child encoding is followed by a series of
622 attribute specifications. Each attribute specification
623 consists of two parts. The first part is an unsigned LEB128
624 number representing the attribute\textquoteright s name. The second part
625 is an unsigned LEB128 number representing the attribute\textquoteright s
626 form. The series of attribute specifications ends with an
627 entry containing 0 for the name and 0 for the form.
630 \DWFORMindirectTARG{} is a special case. For
631 attributes with this form, the attribute value itself in the
634 section begins with an unsigned
635 LEB128 number that represents its form. This allows producers
636 to choose forms for particular attributes
637 \addtoindexx{abbreviations table!dynamic forms in}
639 without having to add a new entry to the abbreviations table.
641 The abbreviations for a given compilation unit end with an
642 entry consisting of a 0 byte for the abbreviation code.
645 Appendix \refersec{app:compilationunitsandabbreviationstableexample}
646 for a depiction of the organization of the
647 debugging information.}
650 \subsection{Attribute Encodings}
651 \label{datarep:attributeencodings}
653 The encodings for the attribute names are given in
654 Table \refersec{tab:attributeencodings}.
656 The attribute form governs how the value of the attribute is
657 encoded. There are nine classes of form, listed below. Each
658 class is a set of forms which have related representations
659 and which are given a common interpretation according to the
660 attribute in which the form is used.
662 Form \DWFORMsecoffsetTARG{}
664 \addtoindexx{rangelistptr class}
666 \addtoindexx{macptr class}
668 \addtoindexx{loclistptr class}
670 \addtoindexx{lineptr class}
671 namely \livelink{chap:classlineptr}{lineptr},
672 \livelink{chap:classloclistptr}{loclistptr},
673 \livelink{chap:classmacptr}{macptr} or
674 \livelink{chap:classrangelistptr}{rangelistptr}; the list
675 of classes allowed by the applicable attribute in
676 Table \refersec{tab:attributeencodings}
677 determines the class of the form.
679 \textit{In DWARF V3 the forms \DWFORMdatafour{} and
680 \DWFORMdataeight{} were
681 \addtoindexx{lineptr class}
683 \addtoindexx{rangelistptr class}
685 \addtoindexx{macptr class}
687 \addtoindexx{loclistptr class}
688 class constant \addtoindexx{constant class}
689 or one of the classes
690 \livelink{chap:classlineptr}{lineptr},
691 \livelink{chap:classloclistptr}{loclistptr},
692 \livelink{chap:classmacptr}{macptr} or
693 \livelink{chap:classrangelistptr}{rangelistptr}, depending on context. In
695 \DWFORMdatafour{} and
696 \DWFORMdataeight{} are members of class
697 constant in all cases.
699 \DWFORMsecoffset{} replaces
700 their usage for the other classes.}
702 Each possible form belongs to one or more of the following classes:
705 \item \livelinki{chap:classaddress}{address}{address class} \\
706 \livetarg{datarep:classaddress}{}
707 Represented as an object of appropriate size to hold an
708 address on the target machine
711 encoded in the compilation unit header
712 (see Section \refersec{datarep:compilationunitheader}).
713 This address is relocatable in a relocatable object file and
714 is relocated in an executable file or shared object.
717 \item \livelink{chap:classblock}{block} \\
718 \livetarg{datarep:classblock}{}
719 Blocks come in four forms:
721 \begin{myindentpara}{1cm}
722 A 1\dash byte length followed by 0 to 255 contiguous information
723 bytes (\DWFORMblockoneTARG).
726 \begin{myindentpara}{1cm}
727 A 2\dash byte length followed by 0 to 65,535 contiguous information
728 bytes (\DWFORMblocktwoTARG).
731 \begin{myindentpara}{1cm}
732 A 4\dash byte length followed by 0 to 4,294,967,295 contiguous
733 information bytes (\DWFORMblockfourTARG).
736 \begin{myindentpara}{1cm}
737 An unsigned LEB128 length followed by the number of bytes
738 specified by the length (\DWFORMblockTARG).
741 In all forms, the length is the number of information bytes
742 that follow. The information bytes may contain any mixture
743 of relocated (or relocatable) addresses, references to other
744 debugging information entries or data bytes.
746 \item \livelinki{chap:classconstant}{constant}{constant class} \\
747 \livetarg{datarep:classconstant}{}
748 There are six forms of constants. There are fixed length
749 constant data forms for one, two, four and eight byte values
754 and \DWFORMdataeightTARG).
755 There are also variable length constant
756 data forms encoded using LEB128 numbers (see below). Both
757 signed (\DWFORMsdataTARG) and unsigned
758 (\DWFORMudataTARG) variable
759 length constants are available
761 The data in \DWFORMdataone,
763 \DWFORMdatafour{} and
765 can be anything. Depending on context, it may
766 be a signed integer, an unsigned integer, a floating\dash point
767 constant, or anything else. A consumer must use context to
768 know how to interpret the bits, which if they are target
769 machine data (such as an integer or floating point constant)
770 will be in target machine byte\dash order.
772 \textit{If one of the \DWFORMdataTARG\textless n\textgreater
773 forms is used to represent a
774 signed or unsigned integer, it can be hard for a consumer
775 to discover the context necessary to determine which
776 interpretation is intended. Producers are therefore strongly
777 encouraged to use \DWFORMsdata{} or
778 \DWFORMudata{} for signed and
779 unsigned integers respectively, rather than
780 \DWFORMdata\textless n\textgreater.}
783 \item \livelinki{chap:classexprloc}{exprloc}{exprloc class} \\
784 \livetarg{datarep:classexprloc}{}
785 This is an unsigned LEB128 length followed by the
786 number of information bytes specified by the length
787 (\DWFORMexprlocTARG).
788 The information bytes contain a DWARF expression
789 (see Section \refersec{chap:dwarfexpressions})
790 or location description
791 (see Section \refersec{chap:locationdescriptions}).
793 \item \livelinki{chap:classflag}{flag}{flag class} \\
794 \livetarg{datarep:classflag}{}
795 A flag \addtoindexx{flag class}
796 is represented explicitly as a single byte of data
798 implicitly (\DWFORMflagpresentTARG).
800 first case, if the \nolink{flag} has value zero, it indicates the
801 absence of the attribute; if the \nolink{flag} has a non\dash zero value,
802 it indicates the presence of the attribute. In the second
803 case, the attribute is implicitly indicated as present, and
804 no value is encoded in the debugging information entry itself.
806 \item \livelinki{chap:classlineptr}{lineptr}{lineptr class} \\
807 \livetarg{datarep:classlineptr}{}
808 This is an offset into
809 \addtoindexx{section offset!in class lineptr value}
811 \dotdebugline{} section
813 It consists of an offset from the beginning of the
815 section to the first byte of
816 the data making up the line number list for the compilation
818 It is relocatable in a relocatable object file, and
819 relocated in an executable or shared object. In the
820 \thirtytwobitdwarfformat, this offset is a 4\dash byte unsigned value;
821 in the \sixtyfourbitdwarfformat, it is an 8\dash byte unsigned value
822 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
825 \item \livelinki{chap:classloclistptr}{loclistptr}{loclistptr class} \\
826 \livetarg{datarep:classloclistptr}{}
827 This is an offset into the
831 It consists of an offset from the
832 \addtoindexx{section offset!in class loclistptr value}
835 section to the first byte of
836 the data making up the
837 \addtoindex{location list} for the compilation unit.
838 It is relocatable in a relocatable object file, and
839 relocated in an executable or shared object. In the
840 \thirtytwobitdwarfformat, this offset is a 4\dash byte unsigned value;
841 in the \sixtyfourbitdwarfformat, it is an 8\dash byte unsigned value
842 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
845 \item \livelinki{chap:classmacptr}{macptr}{macptr class} \\
846 \livetarg{datarep:classmacptr}{}
848 \addtoindexx{section offset!in class macptr value}
850 \dotdebugmacinfo{} section
852 It consists of an offset from the
853 beginning of the \dotdebugmacinfo{}
854 section to the first byte of
855 the data making up the macro information list for the compilation
857 It is relocatable in a relocatable object file, and
858 relocated in an executable or shared object. In the
859 \thirtytwobitdwarfformat, this offset is a 4\dash byte unsigned value;
860 in the \sixtyfourbitdwarfformat, it is an 8\dash byte unsigned value
861 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
864 \item \livelinki{chap:classrangelistptr}{rangelistptr}{rangelistptr class} \\
865 \livetarg{datarep:classrangelistptr}{}
867 \addtoindexx{section offset!in class rangelistptr value}
868 offset into the \dotdebugranges{} section
871 offset from the beginning of the
872 \dotdebugranges{} section
873 to the beginning of the non\dash contiguous address ranges
874 information for the referencing entity.
876 a relocatable object file, and relocated in an executable or
877 shared object. In the \thirtytwobitdwarfformat, this offset
878 is a 4\dash byte unsigned value; in the 64\dash bit DWARF
879 format, it is an 8\dash byte unsigned value (see Section
880 \refersec{datarep:32bitand64bitdwarfformats}).
883 \textit{Because classes \livelink{chap:classlineptr}{lineptr},
884 \livelink{chap:classloclistptr}{loclistptr},
885 \livelink{chap:classmacptr}{macptr} and
886 \livelink{chap:classrangelistptr}{rangelistptr}
887 share a common representation, it is not possible for an
888 attribute to allow more than one of these classes}
892 \item \livelinki{chap:classreference}{reference}{reference class} \\
893 \livetarg{datarep:classreference}{}
894 There are three types of reference.
897 \addtoindexx{reference class}
898 first type of reference can identify any debugging
899 information entry within the containing unit.
902 \addtoindexx{section offset!in class reference value}
903 offset from the first byte of the compilation
904 header for the compilation unit containing the reference. There
905 are five forms for this type of reference. There are fixed
906 length forms for one, two, four and eight byte offsets
907 (respectively, \DWFORMrefoneTARG,
910 and \DWFORMrefeightTARG).
911 There is also an unsigned variable
912 length offset encoded form that uses unsigned LEB128 numbers
913 (\DWFORMrefudataTARG).
914 Because this type of reference is within
915 the containing compilation unit no relocation of the value
918 The second type of reference can identify any debugging
919 information entry within a
920 \dotdebuginfo{} section; in particular,
921 it may refer to an entry in a different compilation unit
922 from the unit containing the reference, and may refer to an
923 entry in a different shared object. This type of reference
925 is an offset from the beginning of the
927 section of the target executable or shared object;
928 it is relocatable in a relocatable object file and frequently
929 relocated in an executable file or shared object. For
930 references from one shared object or static executable file
931 to another, the relocation and identification of the target
932 object must be performed by the consumer. In the
933 \thirtytwobitdwarfformat, this offset is a 4\dash byte unsigned value;
934 in the \sixtyfourbitdwarfformat, it is an 8\dash byte
936 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
938 \textit{A debugging information entry that may be referenced by
939 another compilation unit using
940 \DWFORMrefaddr{} must have a
941 global symbolic name.}
943 \textit{For a reference from one executable or shared object to
944 another, the reference is resolved by the debugger to identify
945 the shared object or executable and the offset into that
946 object\textquoteright s \dotdebuginfo{}
947 section in the same fashion as the run
948 time loader, either when the debug information is first read,
949 or when the reference is used.}
951 The third type of reference can identify any debugging
952 information type entry that has been placed in its own
953 \addtoindex{type unit}. This type of
954 reference (\DWFORMrefsigeightTARG) is the
955 \addtoindexx{type signature}
956 64\dash bit type signature
957 (see Section \refersec{datarep:typesignaturecomputation})
961 \textit{The use of compilation unit relative references will reduce the
962 number of link\dash time relocations and so speed up linking. The
963 use of the second and third type of reference allows for the
964 sharing of information, such as types, across compilation
967 \textit{A reference to any kind of compilation unit identifies the
968 debugging information entry for that unit, not the preceding
971 \item \livelinki{chap:classstring}{string}{string class} \\
972 \livetarg{datarep:classstring}{}
973 A string is a sequence of contiguous non\dash null bytes followed by
975 \addtoindexx{string class}
976 A string may be represented immediately in the
977 debugging information entry itself
978 (\DWFORMstringTARG), or may
980 \addtoindexx{section offset!in class string value}
981 offset into a string table contained in
982 the \dotdebugstr{} section of the object file
983 (\DWFORMstrpTARG). In
984 the \thirtytwobitdwarfformat, the representation of a
986 value is a 4\dash byte unsigned offset; in the \sixtyfourbitdwarfformat,
987 it is an 8\dash byte unsigned offset
988 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
990 If the \DWATuseUTFeight{}
991 \addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} attribute is specified for the
992 compilation unit entry, string values are encoded using the
993 UTF\dash 8 (\addtoindex{Unicode} Transformation Format\dash 8) from the Universal
994 Character Set standard (ISO/IEC 10646\dash 1:1993). Otherwise,
995 the string representation is unspecified.
997 \textit{The \addtoindex{Unicode} Standard Version 3 is fully compatible with
998 ISO/IEC 10646\dash 1:1993. It contains all the same characters
999 and encoding points as ISO/IEC 10646, as well as additional
1000 information about the characters and their use.}
1002 \textit{Earlier versions of DWARF did not specify the representation
1003 of strings; for compatibility, this version also does
1004 not. However, the UTF\dash 8 representation is strongly recommended.}
1008 In no case does an attribute use
1009 \addtoindexx{rangelistptr class}
1011 \addtoindexx{loclistptr class}
1013 \addtoindexx{lineptr class}
1015 \addtoindexx{macptr class}
1016 classes \livelink{chap:classlineptr}{lineptr},
1017 \livelink{chap:classloclistptr}{loclistptr}, \livelink{chap:classmacptr}{macptr} or
1018 \livelink{chap:classrangelistptr}{rangelistptr} to point into either the
1019 \dotdebuginfo{} or \dotdebugstr{} section.
1021 The form encodings are listed in
1022 Table \refersec{tab:attributeformencodings}.
1026 \setlength{\extrarowheight}{0.1cm}
1027 \begin{longtable}{l|l|l}
1028 \caption{Attribute encodings}
1029 \label{tab:attributeencodings}
1030 \addtoindexx{attribute encodings} \\
1031 \hline \bfseries Attribute name&\bfseries Value &\bfseries Classes \\ \hline
1033 \bfseries Attribute name&\bfseries Value &\bfseries Classes\\ \hline
1035 \hline \emph{Continued on next page}
1037 \hline \ddag\ \textit{New in DWARF Version 5}
1039 \DWATsibling&0x01&\livelink{chap:classreference}{reference}
1040 \addtoindexx{sibling attribute!encoding} \\
1041 \DWATlocation&0x02&\livelink{chap:classexprloc}{exprloc},
1042 \livelink{chap:classloclistptr}{loclistptr}\addtoindexx{location attribute!encoding} \\
1043 \DWATname&0x03&\livelink{chap:classstring}{string}
1044 \addtoindexx{name attribute!encoding} \\
1045 \DWATordering&0x09&\livelink{chap:classconstant}{constant}
1046 \addtoindexx{ordering attribute!encoding} \\
1047 \DWATbytesize&0x0b&\livelink{chap:classconstant}{constant}, \livelink{chap:classexprloc}{exprloc},
1048 \livelink{chap:classreference}{reference} \addtoindexx{byte size attribute!encoding} \\
1049 \DWATbitoffset&0x0c&\livelink{chap:classconstant}{constant},
1050 \livelink{chap:classexprloc}{exprloc}, \livelink{chap:classreference}{reference} \addtoindexx{bit offset attribute!encoding} \\
1051 \DWATbitsize&0x0d&\livelink{chap:classconstant}{constant},
1052 \livelink{chap:classexprloc}{exprloc}, \livelink{chap:classreference}{reference} \addtoindexx{bit size attribute!encoding} \\
1053 \DWATstmtlist&0x10&\livelink{chap:classlineptr}{lineptr}
1054 \addtoindexx{statement list attribute!encoding} \\
1055 \DWATlowpc&0x11&\livelink{chap:classaddress}{address}
1056 \addtoindexx{low PC attribute!encoding} \\
1057 \DWAThighpc&0x12&\livelink{chap:classaddress}{address}, \livelink{chap:classconstant}{constant}
1058 \addtoindexx{high PC attribute!encoding} \\
1059 \DWATlanguage&0x13&\livelink{chap:classconstant}{constant}
1060 \addtoindexx{language attribute!encoding} \\
1061 \DWATdiscr&0x15&\livelink{chap:classreference}{reference}
1062 \addtoindexx{discriminant attribute!encoding} \\
1063 \DWATdiscrvalue&0x16&\livelink{chap:classconstant}{constant}
1064 \addtoindexx{discriminant value attribute!encoding} \\
1065 \DWATvisibility&0x17&\livelink{chap:classconstant}{constant}
1066 \addtoindexx{visibility attribute!encoding} \\
1067 \DWATimport&0x18&\livelink{chap:classreference}{reference}
1068 \addtoindexx{import attribute!encoding} \\
1069 \DWATstringlength&0x19&\livelink{chap:classexprloc}{exprloc},
1070 \livelink{chap:classloclistptr}{loclistptr} \addtoindexx{string length attribute!encoding} \\
1071 \DWATcommonreference&0x1a&\livelink{chap:classreference}{reference}
1072 \addtoindexx{common reference attribute!encoding} \\
1073 \DWATcompdir&0x1b&\livelink{chap:classstring}{string}
1074 \addtoindexx{compilation directory attribute!encoding} \\
1075 \DWATconstvalue&0x1c&\livelink{chap:classblock}{block}, \livelink{chap:classconstant}{constant}, \livelink{chap:classstring}{string}
1076 \addtoindexx{constant value attribute!encoding} \\
1077 \DWATcontainingtype&0x1d&\livelink{chap:classreference}{reference}
1078 \addtoindexx{containing type attribute!encoding} \\
1079 \DWATdefaultvalue&0x1e&\livelink{chap:classreference}{reference}
1080 \addtoindexx{default value attribute!encoding} \\
1081 \DWATinline&0x20&\livelink{chap:classconstant}{constant}
1082 \addtoindexx{inline attribute!encoding} \\
1083 \DWATisoptional&0x21&\livelink{chap:classflag}{flag}
1084 \addtoindexx{is optional attribute!encoding} \\
1085 \DWATlowerbound&0x22&\livelink{chap:classconstant}{constant},
1086 \livelink{chap:classexprloc}{exprloc}, \livelink{chap:classreference}{reference} \addtoindexx{lower bound attribute!encoding} \\
1087 \DWATproducer&0x25&\livelink{chap:classstring}{string} \addtoindexx{producer attribute!encoding} \\
1088 \DWATprototyped&0x27&\livelink{chap:classflag}{flag}
1089 \addtoindexx{prototyped attribute!encoding} \\
1090 \DWATreturnaddr&0x2a&\livelink{chap:classexprloc}{exprloc},
1091 \livelink{chap:classloclistptr}{loclistptr} \addtoindexx{return address attribute!encoding} \\
1092 % FIXME: lower case , not Constant
1093 \DWATstartscope&0x2c&\livelink{chap:classconstant}{constant},
1094 \livelink{chap:classrangelistptr}{rangelistptr} \addtoindexx{start scope attribute!encoding} \\
1095 \DWATbitstride&0x2e&\livelink{chap:classconstant}{constant},
1096 \livelink{chap:classexprloc}{exprloc}, \livelink{chap:classreference}{reference} \addtoindexx{bit stride attribute!encoding} \\
1097 \DWATupperbound&0x2f&\livelink{chap:classconstant}{constant},
1098 \livelink{chap:classexprloc}{exprloc}, \livelink{chap:classreference}{reference} \addtoindexx{upper bound attribute!encoding} \\
1099 \DWATabstractorigin&0x31&\livelink{chap:classreference}{reference}
1100 \addtoindexx{abstract origin attribute!encoding} \\
1101 \DWATaccessibility&0x32&\livelink{chap:classconstant}{constant}
1102 \addtoindexx{accessibility attribute!encoding} \\
1103 \DWATaddressclass&0x33&\livelink{chap:classconstant}{constant}
1104 \addtoindexx{address class attribute!encoding} \\
1105 \DWATartificial&0x34&\livelink{chap:classflag}{flag}
1106 \addtoindexx{artificial attribute!encoding} \\
1107 \DWATbasetypes&0x35&\livelink{chap:classreference}{reference}
1108 \addtoindexx{base types attribute!encoding} \\
1109 \DWATcallingconvention&0x36&\livelink{chap:classconstant}{constant}
1110 \addtoindexx{calling convention attribute!encoding} \\
1111 \DWATcount&0x37&\livelink{chap:classconstant}{constant}, \livelink{chap:classexprloc}{exprloc}, \livelink{chap:classreference}{reference}
1112 \addtoindexx{count attribute!encoding} \\
1113 \DWATdatamemberlocation&0x38&\livelink{chap:classconstant}{constant},
1114 \livelink{chap:classexprloc}{exprloc}, \livelink{chap:classloclistptr}{loclistptr}
1115 \addtoindexx{data member attribute!encoding} \\
1116 \DWATdeclcolumn&0x39&\livelink{chap:classconstant}{constant}
1117 \addtoindexx{declaration column attribute!encoding} \\
1118 \DWATdeclfile&0x3a&\livelink{chap:classconstant}{constant}
1119 \addtoindexx{declaration file attribute!encoding} \\
1120 \DWATdeclline&0x3b&\livelink{chap:classconstant}{constant}
1121 \addtoindexx{declaration line attribute!encoding} \\
1122 \DWATdeclaration&0x3c&\livelink{chap:classflag}{flag}
1123 \addtoindexx{declaration attribute!encoding} \\
1124 \DWATdiscrlist&0x3d&\livelink{chap:classblock}{block}
1125 \addtoindexx{discriminant list attribute!encoding} \\
1126 \DWATencoding&0x3e&\livelink{chap:classconstant}{constant}
1127 \addtoindexx{encoding attribute!encoding} \\
1128 \DWATexternal&\xiiif&\livelink{chap:classflag}{flag}
1129 \addtoindexx{external attribute!encoding} \\
1130 \DWATframebase&0x40&\livelink{chap:classexprloc}{exprloc},
1131 \livelink{chap:classloclistptr}{loclistptr} \addtoindexx{frame base attribute!encoding} \\
1132 \DWATfriend&0x41&\livelink{chap:classreference}{reference}
1133 \addtoindexx{friend attribute!encoding} \\
1134 \DWATidentifiercase&0x42&\livelink{chap:classconstant}{constant}
1135 \addtoindexx{identifier case attribute!encoding} \\
1136 \DWATmacroinfo&0x43&\livelink{chap:classmacptr}{macptr}
1137 \addtoindexx{macro information attribute!encoding} \\
1138 \DWATnamelistitem&0x44&\livelink{chap:classreference}{reference}
1139 \addtoindexx{name list item attribute!encoding} \\
1140 \DWATpriority&0x45&\livelink{chap:classreference}{reference}
1141 \addtoindexx{priority attribute!encoding} \\
1142 \DWATsegment&0x46&\livelink{chap:classexprloc}{exprloc},
1143 \livelink{chap:classloclistptr}{loclistptr} \addtoindexx{segment attribute!encoding} \\
1144 \DWATspecification&0x47&\livelink{chap:classreference}{reference}
1145 \addtoindexx{specification attribute!encoding} \\
1146 \DWATstaticlink&0x48&\livelink{chap:classexprloc}{exprloc},
1147 \livelink{chap:classloclistptr}{loclistptr} \addtoindexx{static link attribute!encoding} \\
1148 \DWATtype&0x49&\livelink{chap:classreference}{reference}
1149 \addtoindexx{type attribute!encoding} \\
1150 \DWATuselocation&0x4a&\livelink{chap:classexprloc}{exprloc},
1151 \livelink{chap:classloclistptr}{loclistptr} \addtoindexx{location list attribute!encoding} \\
1152 \DWATvariableparameter&0x4b&\livelink{chap:classflag}{flag}
1153 \addtoindexx{variable parameter attribute!encoding} \\
1154 \DWATvirtuality&0x4c&\livelink{chap:classconstant}{constant}
1155 \addtoindexx{virtuality attribute!encoding} \\
1156 \DWATvtableelemlocation&0x4d&\livelink{chap:classexprloc}{exprloc},
1157 \livelink{chap:classloclistptr}{loclistptr} \addtoindexx{vtable element location attribute!encoding} \\
1158 \DWATallocated&0x4e&\livelink{chap:classconstant}{constant}, \livelink{chap:classexprloc}{exprloc},
1159 \livelink{chap:classreference}{reference} \addtoindexx{allocated attribute!encoding} \\
1160 \DWATassociated&0x4f&\livelink{chap:classconstant}{constant}, \livelink{chap:classexprloc}{exprloc},
1161 \livelink{chap:classreference}{reference} \addtoindexx{associated attribute!encoding} \\
1162 \DWATdatalocation&0x50&\livelink{chap:classexprloc}{exprloc}
1163 \addtoindexx{data location attribute!encoding} \\
1164 \DWATbytestride&0x51&\livelink{chap:classconstant}{constant}, \livelink{chap:classexprloc}{exprloc},
1165 \livelink{chap:classreference}{reference} \addtoindexx{byte stride attribute!encoding} \\
1166 \DWATentrypc&0x52&\livelink{chap:classaddress}{address}
1167 \addtoindexx{entry pc attribute!encoding} \\
1168 \DWATuseUTFeight&0x53&\livelink{chap:classflag}{flag}
1169 \addtoindexx{use UTF8 attribute!encoding}\addtoindexx{UTF-8} \\
1170 \DWATextension&0x54&\livelink{chap:classreference}{reference}
1171 \addtoindexx{extension attribute!encoding} \\
1172 \DWATranges&0x55&\livelink{chap:classrangelistptr}{rangelistptr}
1173 \addtoindexx{ranges attribute!encoding} \\
1174 \DWATtrampoline&0x56&\livelink{chap:classaddress}{address}, \livelink{chap:classflag}{flag},
1175 \livelink{chap:classreference}{reference}, \livelink{chap:classstring}{string} \addtoindexx{trampoline attribute!encoding} \\
1176 \DWATcallcolumn&0x57&\livelink{chap:classconstant}{constant}
1177 \addtoindexx{call column attribute!encoding} \\
1178 \DWATcallfile&0x58&\livelink{chap:classconstant}{constant}
1179 \addtoindexx{call file attribute!encoding} \\
1180 \DWATcallline&0x59&\livelink{chap:classconstant}{constant}
1181 \addtoindexx{call line attribute!encoding} \\
1182 \DWATdescription&0x5a&\livelink{chap:classstring}{string}
1183 \addtoindexx{description attribute!encoding} \\
1184 \DWATbinaryscale&0x5b&\livelink{chap:classconstant}{constant}
1185 \addtoindexx{binary scale attribute!encoding} \\
1186 \DWATdecimalscale&0x5c&\livelink{chap:classconstant}{constant}
1187 \addtoindexx{decimal scale attribute!encoding} \\
1188 \DWATsmall{} &0x5d&\livelink{chap:classreference}{reference}
1189 \addtoindexx{small attribute!encoding} \\
1190 \DWATdecimalsign&0x5e&\livelink{chap:classconstant}{constant}
1191 \addtoindexx{decimal scale attribute!encoding} \\
1192 \DWATdigitcount&0x5f&\livelink{chap:classconstant}{constant}
1193 \addtoindexx{digit count attribute!encoding} \\
1194 \DWATpicturestring&0x60&\livelink{chap:classstring}{string}
1195 \addtoindexx{picture string attribute!encoding} \\
1196 \DWATmutable&0x61&\livelink{chap:classflag}{flag}
1197 \addtoindexx{mutable attribute!encoding} \\
1198 \DWATthreadsscaled&0x62&\livelink{chap:classflag}{flag}
1199 \addtoindexx{thread scaled attribute!encoding} \\
1200 \DWATexplicit&0x63&\livelink{chap:classflag}{flag}
1201 \addtoindexx{explicit attribute!encoding} \\
1202 \DWATobjectpointer&0x64&\livelink{chap:classreference}{reference}
1203 \addtoindexx{object pointer attribute!encoding} \\
1204 \DWATendianity&0x65&\livelink{chap:classconstant}{constant}
1205 \addtoindexx{endianity attribute!encoding} \\
1206 \DWATelemental&0x66&\livelink{chap:classflag}{flag}
1207 \addtoindexx{elemental attribute!encoding} \\
1208 \DWATpure&0x67&\livelink{chap:classflag}{flag}
1209 \addtoindexx{pure attribute!encoding} \\
1210 \DWATrecursive&0x68&\livelink{chap:classflag}{flag}
1211 \addtoindexx{recursive attribute!encoding} \\
1212 \DWATsignature{} &0x69&\livelink{chap:classreference}{reference}
1213 \addtoindexx{signature attribute!encoding} \\
1214 \DWATmainsubprogram{} &0x6a&\livelink{chap:classflag}{flag}
1215 \addtoindexx{main subprogram attribute!encoding} \\
1216 \DWATdatabitoffset{} &0x6b&\livelink{chap:classconstant}{constant}
1217 \addtoindexx{data bit offset attribute!encoding} \\
1218 \DWATconstexpr{} &0x6c&\livelink{chap:classflag}{flag}
1219 \addtoindexx{constant expression attribute!encoding} \\
1220 \DWATenumclass{} &0x6d&\livelink{chap:classflag}{flag}
1221 \addtoindexx{enumeration class attribute!encoding} \\
1222 \DWATlinkagename{} &0x6e&\livelink{chap:classstring}{string}
1223 \addtoindexx{linkage name attribute!encoding} \\
1224 \DWATstringlengthbitsize{} \ddag&0x6f&
1225 \livelink{chap:classconstant}{constant}\addtoindexx{string length attribute!size of length} \\
1226 \DWATstringlengthbytesize{} \ddag&0x70&
1227 \livelink{chap:classconstant}{constant}\addtoindexx{string length attribute!size of length} \\
1228 \DWATrank~\ddag&0x71&
1229 \livelink{chap:DWATrank}{constant, exprloc}\addtoindexx{rank attribute!encoding} \\
1230 \DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding} \\
1231 \DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding} \\
1238 \setlength{\extrarowheight}{0.1cm}
1239 \begin{longtable}{l|l|l}
1240 \caption{Attribute form encodings} \label{tab:attributeformencodings} \\
1241 \hline \bfseries Form name&\bfseries Value &\bfseries Classes \\ \hline
1243 \bfseries Form name&\bfseries Value &\bfseries Classes\\ \hline
1245 \hline \emph{Continued on next page}
1250 \DWFORMaddr &0x01&\livelink{chap:classaddress}{address} \\
1251 \DWFORMblocktwo &0x03&\livelink{chap:classblock}{block} \\
1252 \DWFORMblockfour &0x04&\livelink{chap:classblock}{block} \\
1253 \DWFORMdatatwo &0x05&\livelink{chap:classconstant}{constant} \\
1254 \DWFORMdatafour &0x06&\livelink{chap:classconstant}{constant} \\
1255 \DWFORMdataeight &0x07&\livelink{chap:classconstant}{constant} \\
1256 \DWFORMstring&0x08&\livelink{chap:classstring}{string} \\
1257 \DWFORMblock&0x09&\livelink{chap:classblock}{block} \\
1258 \DWFORMblockone &0x0a&\livelink{chap:classblock}{block} \\
1259 \DWFORMdataone &\livelink{chap:classconstant}{constant} \\
1260 \DWFORMflag&0x0c&\livelink{chap:classflag}{flag} \\
1261 \DWFORMsdata&0x0d&\livelink{chap:classconstant}{constant} \\
1262 \DWFORMstrp&0x0e&\livelink{chap:classstring}{string} \\
1263 \DWFORMudata&0x0f&\livelink{chap:classconstant}{constant} \\
1264 \DWFORMrefaddr&0x10&\livelink{chap:classreference}{reference} \\
1265 \DWFORMrefone&0x11&\livelink{chap:classreference}{reference} \\
1266 \DWFORMreftwo&0x12&\livelink{chap:classreference}{reference} \\
1267 \DWFORMreffour&0x13&\livelink{chap:classreference}{reference} \\
1268 \DWFORMrefeight&0x14&\livelink{chap:classreference}{reference} \\
1269 \DWFORMrefudata&0x15&\livelink{chap:classreference}{reference} \\
1270 \DWFORMindirect&0x16&(see Section \refersec{datarep:abbreviationstables}) \\
1271 \DWFORMsecoffset{} &0x17&\livelink{chap:classlineptr}{lineptr}, \livelink{chap:classloclistptr}{loclistptr}, \livelink{chap:classmacptr}{macptr}, \livelink{chap:classrangelistptr}{rangelistptr} \\
1272 \DWFORMexprloc{} &0x18&\livelink{chap:classexprloc}{exprloc} \\
1273 \DWFORMflagpresent{} &0x19&\livelink{chap:classflag}{flag} \\
1274 \DWFORMrefsigeight &0x20&\livelink{chap:classreference}{reference} \\
1281 \section{Variable Length Data}
1282 \label{datarep:variablelengthdata}
1283 \addtoindexx{variable length data|see {LEB128}}
1285 \addtoindexx{Little Endian Base 128|see{LEB128}}
1286 encoded using \doublequote{Little Endian Base 128}
1287 \addtoindexx{little-endian encoding|see{endian attribute}}
1289 \addtoindexx{LEB128}
1290 LEB128 is a scheme for encoding integers
1291 densely that exploits the assumption that most integers are
1294 \textit{This encoding is equally suitable whether the target machine
1295 architecture represents data in big\dash\ endian or little\dash endian
1296 order. It is \doublequote{little\dash endian} only in the sense that it
1297 avoids using space to represent the \doublequote{big} end of an
1298 unsigned integer, when the big end is all zeroes or sign
1301 Unsigned LEB128 (ULEB128) numbers are encoded as follows:
1302 \addtoindexx{LEB128!unsigned, encoding as}
1303 start at the low order end of an unsigned integer and chop
1304 it into 7\dash bit chunks. Place each chunk into the low order 7
1305 bits of a byte. Typically, several of the high order bytes
1306 will be zero; discard them. Emit the remaining bytes in a
1307 stream, starting with the low order byte; set the high order
1308 bit on each byte except the last emitted byte. The high bit
1309 of zero on the last byte indicates to the decoder that it
1310 has encountered the last byte.
1312 The integer zero is a special case, consisting of a single
1315 Table \refersec{tab:examplesofunsignedleb128encodings}
1316 gives some examples of unsigned LEB128 numbers. The
1317 0x80 in each case is the high order bit of the byte, indicating
1318 that an additional byte follows.
1321 The encoding for signed, two\textquoteright s complement LEB128 (SLEB128)
1322 \addtoindexx{LEB128!signed, encoding as}
1323 numbers is similar, except that the criterion for discarding
1324 high order bytes is not whether they are zero, but whether
1325 they consist entirely of sign extension bits. Consider the
1326 32\dash bit integer -2. The three high level bytes of the number
1327 are sign extension, thus LEB128 would represent it as a single
1328 byte containing the low order 7 bits, with the high order
1329 bit cleared to indicate the end of the byte stream. Note
1330 that there is nothing within the LEB128 representation that
1331 indicates whether an encoded number is signed or unsigned. The
1332 decoder must know what type of number to expect.
1333 Table \refersec{tab:examplesofunsignedleb128encodings}
1334 gives some examples of unsigned LEB128 numbers and
1335 Table \refersec{tab:examplesofsignedleb128encodings}
1336 gives some examples of signed LEB128
1339 \textit{Appendix \refersec{app:variablelengthdataencodingdecodinginformative}
1340 \addtoindexx{LEB128!examples}
1341 gives algorithms for encoding and decoding these forms.}
1345 \setlength{\extrarowheight}{0.1cm}
1346 \begin{longtable}{l|l|l}
1347 \caption{Examples of unsigned LEB128 encodings}
1348 \label{tab:examplesofunsignedleb128encodings}
1349 \addtoindexx{LEB128 encoding!examples} \\
1350 \hline \bfseries Number&\bfseries First byte &\bfseries Second byte \\ \hline
1352 \bfseries Number&\bfseries First Byte &\bfseries Second byte\\ \hline
1354 \hline \emph{Continued on next page}
1360 128& 0 + 0x80 & 1 \\
1361 129& 1 + 0x80 & 1 \\
1362 130& 2 + 0x80 & 1 \\
1363 12857& 57 + 0x80 & 100 \\
1370 \setlength{\extrarowheight}{0.1cm}
1371 \begin{longtable}{l|l|l}
1372 \caption{Examples of signed LEB128 encodings} \label{tab:examplesofsignedleb128encodings} \\
1373 \hline \bfseries Number&\bfseries First byte &\bfseries Second byte \\ \hline
1375 \bfseries Number&\bfseries First Byte &\bfseries Second byte\\ \hline
1377 \hline \emph{Continued on next page}
1383 127& 127 + 0x80 & 0 \\
1384 -127& 1 + 0x80 & 0x7f \\
1385 128& 0 + 0x80 & 1 \\
1386 -128& 0 + 0x80 & 0x7f \\
1387 129& 1 + 0x80 & 1 \\
1388 -129& 0x7f + 0x80 & 0x7e \\
1395 \section{DWARF Expressions and Location Descriptions}
1396 \label{datarep:dwarfexpressionsandlocationdescriptions}
1397 \subsection{DWARF Expressions}
1398 \label{datarep:dwarfexpressions}
1401 \addtoindexx{DWARF Expression!operator encoding}
1402 DWARF expression is stored in a \nolink{block} of contiguous
1403 bytes. The bytes form a sequence of operations. Each operation
1404 is a 1\dash byte code that identifies that operation, followed by
1405 zero or more bytes of additional data. The encodings for the
1406 operations are described in
1407 Table \refersec{tab:dwarfoperationencodings}.
1410 \setlength{\extrarowheight}{0.1cm}
1411 \begin{longtable}{l|l|c|l}
1412 \caption{DWARF operation encodings} \label{tab:dwarfoperationencodings} \\
1413 \hline & &\bfseries No. of &\\
1414 \bfseries Operation&\bfseries Code &\bfseries Operands &\bfseries Notes\\ \hline
1416 & &\bfseries No. of &\\
1417 \bfseries Operation&\bfseries Code &\bfseries Operands &\bfseries Notes\\ \hline
1419 \hline \emph{Continued on next page}
1424 \DWOPaddr&0x03&1 & constant address \\
1425 & & &(size target specific) \\
1427 \DWOPderef&0x06&0 & \\
1429 \DWOPconstoneu&0x08&1&1\dash byte constant \\
1430 \DWOPconstones&0x09&1&1\dash byte constant \\
1431 \DWOPconsttwou&0x0a&1&2\dash byte constant \\
1432 \DWOPconsttwos&0x0b&1&2\dash byte constant \\
1433 \DWOPconstfouru&0x0c&1&4\dash byte constant \\
1434 \DWOPconstfours&0x0d&1&4\dash byte constant \\
1435 \DWOPconsteightu&0x0e&1&8\dash byte constant \\
1436 \DWOPconsteights&0x0f&1&8\dash byte constant \\
1437 \DWOPconstu&0x10&1&ULEB128 constant \\
1438 \DWOPconsts&0x11&1&SLEB128 constant \\
1439 \DWOPdup&0x12&0 & \\
1440 \DWOPdrop&0x13&0 & \\
1441 \DWOPover&0x14&0 & \\
1442 \DWOPpick&0x15&1&1\dash byte stack index \\
1443 \DWOPswap&0x16&0 & \\
1444 \DWOProt&0x17&0 & \\
1445 \DWOPxderef&0x18&0 & \\
1446 \DWOPabs&0x19&0 & \\
1447 \DWOPand&0x1a&0 & \\
1448 \DWOPdiv&0x1b&0 & \\
1452 \DWOPminus&0x1c&0 & \\
1453 \DWOPmod&0x1d&0 & \\
1454 \DWOPmul&0x1e&0 & \\
1455 \DWOPneg&0x1f&0 & \\
1456 \DWOPnot&0x20&0 & \\
1458 \DWOPplus&0x22&0 & \\
1459 \DWOPplusuconst&0x23&1&ULEB128 addend \\
1460 \DWOPshl&0x24&0 & \\
1461 \DWOPshr&0x25&0 & \\
1462 \DWOPshra&0x26&0 & \\
1463 \DWOPxor&0x27&0 & \\
1465 \DWOPbra&0x28&1 & signed 2\dash byte constant \\
1472 \DWOPskip&0x2f&1&signed 2\dash byte constant \\ \hline
1474 \DWOPlitzero & 0x30 & 0 & \\
1475 \DWOPlitone & 0x31 & 0& literals 0 .. 31 = \\
1476 \ldots & & &\hspace{0.5cm}(\DWOPlitzero{} + literal) \\
1477 \DWOPlitthirtyone & 0x4f & 0 & \\ \hline
1479 \DWOPregzero & 0x50 & 0 & \\
1480 \DWOPregone & 0x51 & 0® 0 .. 31 = \\
1481 \ldots & & &\hspace{0.5cm}(\DWOPregzero{} + regnum) \\
1482 \DWOPregthirtyone & 0x6f & 0 & \\ \hline
1484 \DWOPbregzero & 0x70 &1 & SLEB128 offset \\
1485 \DWOPbregone & 0x71 & 1 &base register 0 .. 31 = \\
1486 ... & & &\hspace{0.5cm}(\DWOPbregzero{} + regnum) \\
1487 \DWOPbregthirtyone & 0x8f & 1 & \\ \hline
1489 \DWOPregx{} & 0x90 &1&ULEB128 register \\
1490 \DWOPfbreg{} & 0x91&1&SLEB128 offset \\
1491 \DWOPbregx{} & 0x92&2 &ULEB128 register followed \\
1492 & & & by SLEB128 offset \\
1493 \DWOPpiece{} & 0x93 &1& ULEB128 size of piece addressed \\
1494 \DWOPderefsize{} & 0x94 &1& 1-byte size of data retrieved \\
1495 \DWOPxderefsize{} & 0x95&1&1-byte size of data retrieved \\
1496 \DWOPnop{} & 0x96 &0& \\
1499 \DWOPpushobjectaddress&0x97&0 & \\
1500 \DWOPcalltwo&0x98&1& 2\dash byte offset of DIE \\
1501 \DWOPcallfour&0x99&1& 4\dash byte offset of DIE \\
1502 \DWOPcallref&0x9a&1& 4\dash\ or 8\dash byte\\
1503 &&& offset of DIE \\
1504 \DWOPformtlsaddress&0x9b &0& \\
1505 \DWOPcallframecfa{} &0x9c &0& \\
1506 \DWOPbitpiece&0x9d &2&ULEB128 size followed by \\
1508 \DWOPimplicitvalue{} &0x9e &2&ULEB128 size followed by \\
1509 &&&\nolink{block} of that size\\
1510 \DWOPstackvalue{} &0x9f &0& \\
1511 \DWOPlouser{} &0xe0 && \\
1512 \DWOPhiuser{} &\xff && \\
1518 \subsection{Location Descriptions}
1519 \label{datarep:locationdescriptions}
1521 A location description is used to compute the
1522 location of a variable or other entity.
1524 \subsection{Location Lists}
1525 \label{datarep:locationlists}
1527 Each entry in a \addtoindex{location list} is either a location list entry,
1528 a base address selection entry, or an
1529 \addtoindexx{end of list entry!in location list}
1532 A \addtoindex{location list} entry consists of two address offsets followed
1533 by a 2\dash byte length, followed by a block of contiguous bytes
1534 that contains a DWARF location description. The length
1535 specifies the number of bytes in that block. The two offsets
1536 are the same size as an address on the target machine.
1539 A base address selection entry and an
1540 \addtoindexx{end of list entry!in location list}
1541 end of list entry each
1542 consist of two (constant or relocated) address offsets. The two
1543 offsets are the same size as an address on the target machine.
1545 For a \addtoindex{location list} to be specified, the base address of
1546 \addtoindexx{base address selection entry!in location list}
1547 the corresponding compilation unit must be defined
1548 (see Section \refersec{chap:normalandpartialcompilationunitentries}).
1550 \section{Base Type Attribute Encodings}
1551 \label{datarep:basetypeattributeencodings}
1553 The encodings of the
1554 \hypertarget{chap:DWATencodingencodingofbasetype}
1556 \addtoindexx{encoding attribute!encoding}
1559 attribute are given in
1560 Table \refersec{tab:basetypeencodingvalues}
1563 \setlength{\extrarowheight}{0.1cm}
1564 \begin{longtable}{l|c}
1565 \caption{Base type encoding values} \label{tab:basetypeencodingvalues} \\
1566 \hline \bfseries Base type encoding code name&\bfseries Value \\ \hline
1568 \bfseries Base type encoding code name&\bfseries Value\\ \hline
1570 \hline \emph{Continued on next page}
1574 \DWATEaddress&0x01 \\
1575 \DWATEboolean&0x02 \\
1576 \DWATEcomplexfloat&0x03 \\
1578 \DWATEsigned&0x05 \\
1579 \DWATEsignedchar&0x06 \\
1580 \DWATEunsigned&0x07 \\
1581 \DWATEunsignedchar&0x08 \\
1582 \DWATEimaginaryfloat&0x09 \\
1583 \DWATEpackeddecimal&0x0a \\
1584 \DWATEnumericstring&0x0b \\
1585 \DWATEedited&0x0c \\
1586 \DWATEsignedfixed&0x0d \\
1587 \DWATEunsignedfixed&0x0e \\
1588 \DWATEdecimalfloat{} & 0x0f \\
1589 \DWATEUTF{} & 0x10 \\
1590 \DWATElouser{} & 0x80 \\
1591 \DWATEhiuser{} & \xff \\
1596 The encodings of the constants used in the
1597 \DWATdecimalsign{} attribute
1599 Table \refersec{tab:decimalsignencodings}.
1602 \setlength{\extrarowheight}{0.1cm}
1603 \begin{longtable}{l|c}
1604 \caption{Decimal sign encodings} \label{tab:decimalsignencodings} \\
1605 \hline \bfseries Decimal sign code name&\bfseries Value \\ \hline
1607 \bfseries Decimal sign code name&\bfseries Value\\ \hline
1609 \hline \emph{Continued on next page}
1614 \DWDSunsigned{} & 0x01 \\
1615 \DWDSleadingoverpunch{} & 0x02 \\
1616 \DWDStrailingoverpunch{} & 0x03 \\
1617 \DWDSleadingseparate{} & 0x04 \\
1618 \DWDStrailingseparate{} & 0x05 \\
1623 The encodings of the constants used in the
1624 \DWATendianity{} attribute are given in
1625 Table \refersec{tab:endianityencodings}.
1628 \setlength{\extrarowheight}{0.1cm}
1629 \begin{longtable}{l|c}
1630 \caption{Endianity encodings} \label{tab:endianityencodings}\\
1631 \hline \bfseries Endian code name&\bfseries Value \\ \hline
1633 \bfseries Endian code name&\bfseries Value\\ \hline
1635 \hline \emph{Continued on next page}
1640 \DWENDdefault{} & 0x00 \\
1641 \DWENDbig{} & 0x01 \\
1642 \DWENDlittle{} & 0x02 \\
1643 \DWENDlouser{} & 0x40 \\
1644 \DWENDhiuser{} & \xff \\
1649 \section{Accessibility Codes}
1650 \label{datarep:accessibilitycodes}
1651 The encodings of the constants used in the
1652 \DWATaccessibility{}
1654 \addtoindexx{accessibility attribute!encoding}
1656 Table \refersec{tab:accessibilityencodings}.
1659 \setlength{\extrarowheight}{0.1cm}
1660 \begin{longtable}{l|c}
1661 \caption{Accessibility encodings} \label{tab:accessibilityencodings}\\
1662 \hline \bfseries Accessibility code name&\bfseries Value \\ \hline
1664 \bfseries Accessibility code name&\bfseries Value\\ \hline
1666 \hline \emph{Continued on next page}
1671 \DWACCESSpublic&0x01 \\
1672 \DWACCESSprotected&0x02 \\
1673 \DWACCESSprivate&0x03 \\
1679 \section{Visibility Codes}
1680 \label{datarep:visibilitycodes}
1681 The encodings of the constants used in the
1682 \DWATvisibility{} attribute are given in
1683 Table \refersec{tab:visibilityencodings}.
1686 \setlength{\extrarowheight}{0.1cm}
1687 \begin{longtable}{l|c}
1688 \caption{Visibility encodings} \label{tab:visibilityencodings}\\
1689 \hline \bfseries Visiibility code name&\bfseries Value \\ \hline
1691 \bfseries Visibility code name&\bfseries Value\\ \hline
1693 \hline \emph{Continued on next page}
1699 \DWVISexported&0x02 \\
1700 \DWVISqualified&0x03 \\
1705 \section{Virtuality Codes}
1706 \label{datarep:vitualitycodes}
1708 The encodings of the constants used in the
1709 \DWATvirtuality{} attribute are given in
1710 Table \refersec{tab:virtualityencodings}.
1713 \setlength{\extrarowheight}{0.1cm}
1714 \begin{longtable}{l|c}
1715 \caption{Virtuality encodings} \label{tab:virtualityencodings}\\
1716 \hline \bfseries Virtuality code name&\bfseries Value \\ \hline
1718 \bfseries Virtuality code name&\bfseries Value\\ \hline
1720 \hline \emph{Continued on next page}
1725 \DWVIRTUALITYnone&0x00 \\
1726 \DWVIRTUALITYvirtual&0x01 \\
1727 \DWVIRTUALITYpurevirtual&0x02 \\
1735 \DWVIRTUALITYnone{} is equivalent to the absence of the
1739 \section{Source Languages}
1740 \label{datarep:sourcelanguages}
1742 The encodings of the constants used
1743 \addtoindexx{language attribute, encoding}
1745 \addtoindexx{language name encoding}
1748 attribute are given in
1749 Table \refersec{tab:languageencodings}.
1751 % If we don't force a following space it looks odd
1753 and their associated values are reserved, but the
1754 languages they represent are not well supported.
1755 Table \refersec{tab:languageencodings}
1757 \addtoindexx{lower bound attribute!default}
1758 default lower bound, if any, assumed for
1759 an omitted \DWATlowerbound{} attribute in the context of a
1760 \DWTAGsubrangetype{} debugging information entry for each
1764 \setlength{\extrarowheight}{0.1cm}
1765 \begin{longtable}{l|c|c}
1766 \caption{Language encodings} \label{tab:languageencodings}\\
1767 \hline \bfseries Language name&\bfseries Value &\bfseries Default Lower Bound \\ \hline
1769 \bfseries Language name&\bfseries Value &\bfseries Default Lower Bound\\ \hline
1771 \hline \emph{Continued on next page}
1774 \dag \ \textit{See text} \\ \ddag \ \textit{New in \addtoindex{DWARF Version 5}}
1777 \DWLANGCeightynine &0x0001 &0 \\
1778 \DWLANGC{} &0x0002 &0 \\
1779 \DWLANGAdaeightythree{} \dag &0x0003 &1 \addtoindexx{Ada} \\
1780 \DWLANGCplusplus{} &0x0004 &0 \\
1781 \DWLANGCobolseventyfour{} \dag &0x0005 &1 \\
1782 \DWLANGCoboleightyfive{} \dag &0x0006 &1 \\
1783 \DWLANGFortranseventyseven &0x0007 &1 \\
1784 \DWLANGFortranninety &0x0008 &1 \\
1785 \DWLANGPascaleightythree &0x0009 &1 \\
1786 \DWLANGModulatwo &0x000a &1 \\
1787 \DWLANGJava &0x000b &0 \\
1788 \DWLANGCninetynine &0x000c &0 \\
1789 \DWLANGAdaninetyfive{} \dag &0x000d &1 \addtoindexx{Ada} \\
1790 \DWLANGFortranninetyfive &0x000e &1 \\
1791 \DWLANGPLI{} \dag &0x000f &1 \\
1792 \DWLANGObjC{} &0x0010 &0 \\
1793 \DWLANGObjCplusplus{} &0x0011 &0 \\
1794 \DWLANGUPC{} &0x0012 &0 \\
1795 \DWLANGD{} &0x0013 &0 \\
1796 \DWLANGPython{} \dag &0x0014 &0 \\
1797 \DWLANGOpenCL{} \dag \ddag &0x0015 &0 \\
1798 \DWLANGGo{} \dag \ddag &0x0016 &0 \\
1799 \DWLANGModulathree{} \dag \ddag &0x0017 &1 \\
1800 \DWLANGHaskell{} \dag \ddag &0x0018 &0 \\
1801 \DWLANGlouser{} &0x8000 & \\
1802 \DWLANGhiuser{} &\xffff & \\
1807 \section{Address Class Encodings}
1808 \label{datarep:addressclassencodings}
1810 The value of the common
1811 \addtoindexi{address}{address class!attribute encoding}
1816 \section{Identifier Case}
1817 \label{datarep:identifiercase}
1819 The encodings of the constants used in the
1820 \DWATidentifiercase{} attribute are given in
1821 Table \refersec{tab:identifiercaseencodings}.
1824 \setlength{\extrarowheight}{0.1cm}
1825 \begin{longtable}{l|c}
1826 \caption{Identifier case encodings} \label{tab:identifiercaseencodings}\\
1827 \hline \bfseries Identifier case name&\bfseries Value \\ \hline
1829 \bfseries Identifier case name&\bfseries Value\\ \hline
1831 \hline \emph{Continued on next page}
1835 \DWIDcasesensitive&0x00 \\
1837 \DWIDdowncase&0x02 \\
1838 \DWIDcaseinsensitive&0x03 \\
1842 \section{Calling Convention Encodings}
1843 \label{datarep:callingconventionencodings}
1844 The encodings of the constants used in the
1845 \DWATcallingconvention{} attribute are given in
1846 Table \refersec{tab:callingconventionencodings}.
1849 \setlength{\extrarowheight}{0.1cm}
1850 \begin{longtable}{l|c}
1851 \caption{Calling convention encodings} \label{tab:callingconventionencodings}\\
1852 \hline \bfseries Calling Convention name&\bfseries Value \\ \hline
1854 \bfseries Calling Convention name&\bfseries Value\\ \hline
1856 \hline \emph{Continued on next page}
1862 \DWCCprogram&0x02 \\
1870 \section{Inline Codes}
1871 \label{datarep:inlinecodes}
1873 The encodings of the constants used in
1874 \addtoindexx{inline attribute!encoding}
1876 \DWATinline{} attribute are given in
1877 Table \refersec{tab:inlineencodings}.
1881 \setlength{\extrarowheight}{0.1cm}
1882 \begin{longtable}{l|c}
1883 \caption{Inline encodings} \label{tab:inlineencodings}\\
1884 \hline \bfseries Inline Code name&\bfseries Value \\ \hline
1886 \bfseries Inline Code name&\bfseries Value\\ \hline
1888 \hline \emph{Continued on next page}
1893 \DWINLnotinlined&0x00 \\
1894 \DWINLinlined&0x01 \\
1895 \DWINLdeclarednotinlined&0x02 \\
1896 \DWINLdeclaredinlined&0x03 \\
1901 % this clearpage is ugly, but the following table came
1902 % out oddly without it.
1904 \section{Array Ordering}
1905 \label{datarep:arrayordering}
1907 The encodings of the constants used in the
1908 \DWATordering{} attribute are given in
1909 Table \refersec{tab:orderingencodings}.
1913 \setlength{\extrarowheight}{0.1cm}
1914 \begin{longtable}{l|c}
1915 \caption{Ordering encodings} \label{tab:orderingencodings}\\
1916 \hline \bfseries Ordering name&\bfseries Value \\ \hline
1918 \bfseries Ordering name&\bfseries Value\\ \hline
1920 \hline \emph{Continued on next page}
1925 \DWORDrowmajor&0x00 \\
1926 \DWORDcolmajor&0x01 \\
1932 \section{Discriminant Lists}
1933 \label{datarep:discriminantlists}
1935 The descriptors used in
1936 \addtoindexx{discriminant list attribute!encoding}
1938 \DWATdiscrlist{} attribute are
1939 encoded as 1\dash byte constants. The
1940 defined values are given in
1941 Table \refersec{tab:discriminantdescriptorencodings}.
1943 % Odd that the 'Name' field capitalized here, it is not caps elsewhere.
1945 \setlength{\extrarowheight}{0.1cm}
1946 \begin{longtable}{l|c}
1947 \caption{Discriminant descriptor encodings} \label{tab:discriminantdescriptorencodings}\\
1948 \hline \bfseries Descriptor Name&\bfseries Value \\ \hline
1950 \bfseries Descriptor Name&\bfseries Value\\ \hline
1952 \hline \emph{Continued on next page}
1964 \section{Name Lookup Tables}
1965 \label{datarep:namelookuptables}
1967 Each set of entries in the table of global names contained
1968 in the \dotdebugpubnames{} and
1969 \dotdebugpubtypes{} sections begins
1970 with a header consisting of:
1971 \begin{enumerate}[1. ]
1973 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
1974 \addttindexx{unit\_length}
1975 A 4\dash byte or 12\dash byte unsigned integer
1976 \addtoindexx{initial length}
1977 representing the length
1978 of the \dotdebuginfo{}
1979 contribution for that compilation unit,
1980 not including the length field itself. In the
1981 \thirtytwobitdwarfformat, this is a 4\dash byte unsigned integer (which must be less
1982 than \xfffffffzero); in the \sixtyfourbitdwarfformat, this consists
1983 of the 4\dash byte value \wffffffff followed by an 8\dash byte unsigned
1984 integer that gives the actual length
1985 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1987 \item version (\addtoindex{uhalf}) \\
1988 A 2\dash byte unsigned integer representing the version of the
1989 DWARF information for the name lookup table
1990 \addtoindexx{version number!name lookup table}
1991 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
1992 The value in this field is 2.
1995 \item \addtoindex{debug\_info\_offset} (section offset) \\
1997 \addtoindexx{section offset!in name lookup table set of entries}
1998 4\dash byte or 8\dash byte
2001 section of the compilation unit header.
2002 In the \thirtytwobitdwarfformat, this is a 4\dash byte unsigned offset;
2003 in the \sixtyfourbitdwarfformat, this is an 8\dash byte unsigned offsets
2004 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2006 \item \addtoindex{debug\_info\_length} (\livelink{datarep:sectionoffsetlength}{section length}) \\
2007 \addtoindexx{section length!in .debug\_pubnames header}
2009 \addtoindexx{section length!in .debug\_pubtypes header}
2010 4\dash byte or 8\dash byte length containing the size in bytes of the
2011 contents of the \dotdebuginfo{}
2012 section generated to represent
2013 this compilation unit. In the \thirtytwobitdwarfformat, this is
2014 a 4\dash byte unsigned length; in the \sixtyfourbitdwarfformat, this
2015 is an 8-byte unsigned length
2016 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2021 This header is followed by a series of tuples. Each tuple
2022 consists of a 4\dash byte or 8\dash byte offset followed by a string
2023 of non\dash null bytes terminated by one null byte.
2025 DWARF format, this is a 4\dash byte offset; in the 64\dash bit DWARF
2026 format, it is an 8\dash byte offset.
2027 Each set is terminated by an
2028 offset containing the value 0.
2032 \section{Address Range Table}
2033 \label{datarep:addrssrangetable}
2035 Each set of entries in the table of address ranges contained
2036 in the \dotdebugaranges{}
2037 section begins with a header containing:
2038 \begin{enumerate}[1. ]
2039 % FIXME The unit length text is not fully consistent across
2042 \item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
2043 \addttindexx{unit\_length}
2044 A 4-byte or 12-byte length containing the length of the
2045 \addtoindexx{initial length}
2046 set of entries for this compilation unit, not including the
2047 length field itself. In the \thirtytwobitdwarfformat, this is a
2048 4-byte unsigned integer (which must be less than \xfffffffzero);
2049 in the \sixtyfourbitdwarfformat, this consists of the 4-byte value
2050 \wffffffff followed by an 8-byte unsigned integer that gives
2052 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2054 \item version (\addtoindex{uhalf}) \\
2055 A 2\dash byte version identifier representing the version of the
2056 DWARF information for the address range table
2057 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
2058 This value in this field \addtoindexx{version number!address range table} is 2.
2061 \item debug\_info\_offset (\livelink{datarep:sectionoffsetlength}{section offset}) \\
2063 \addtoindexx{section offset!in .debug\_aranges header}
2064 4\dash byte or 8\dash byte offset into the
2065 \dotdebuginfo{} section of
2066 the compilation unit header. In the \thirtytwobitdwarfformat,
2067 this is a 4\dash byte unsigned offset; in the \sixtyfourbitdwarfformat,
2068 this is an 8\dash byte unsigned offset
2069 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
2071 \item address\_size (ubyte) \\
2072 A 1\dash byte unsigned integer containing the size in bytes of an
2073 \addtoindexx{address\_size}
2075 \addtoindexx{size of an address}
2076 (or the offset portion of an address for segmented
2077 \addtoindexx{address space!segmented}
2078 addressing) on the target system.
2080 \item segment\_size (ubyte) \\
2082 \addtoindexx{segment\_size}
2083 1\dash byte unsigned integer containing the size in bytes of a
2084 segment selector on the target system.
2088 This header is followed by a series of tuples. Each tuple
2089 consists of a segment, an address and a length.
2091 size is given by the \addtoindex{segment\_size} field of the header; the
2092 address and length size are each given by the address\_size
2093 field of the header.
2094 The first tuple following the header in
2095 each set begins at an offset that is a multiple of the size
2096 of a single tuple (that is, the size of a segment selector
2097 plus twice the \addtoindex{size of an address}).
2098 The header is padded, if
2099 necessary, to that boundary. Each set of tuples is terminated
2100 by a 0 for the segment, a 0 for the address and 0 for the
2101 length. If the \addtoindex{segment\_size} field in the header is zero,
2102 the segment selectors are omitted from all tuples, including
2103 the terminating tuple.
2106 \section{Line Number Information}
2107 \label{datarep:linenumberinformation}
2109 The \addtoindexi{version number}{version number!line number information}
2110 in the line number program header is 4
2111 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
2113 The boolean values \doublequote{true} and \doublequote{false}
2114 used by the line number information program are encoded
2115 as a single byte containing the value 0
2116 for \doublequote{false,} and a non-zero value for \doublequote{true.}
2118 The encodings for the standard opcodes are given in
2119 \addtoindexx{line number opcodes!standard opcode encoding}
2120 Table \refersec{tab:linenumberstandardopcodeencodings}.
2122 % Odd that the 'Name' field capitalized here, it is not caps elsewhere.
2124 \setlength{\extrarowheight}{0.1cm}
2125 \begin{longtable}{l|c}
2126 \caption{Line number standard opcode encodings} \label{tab:linenumberstandardopcodeencodings}\\
2127 \hline \bfseries Opcode name&\bfseries Value \\ \hline
2129 \bfseries Opcode name&\bfseries Value\\ \hline
2131 \hline \emph{Continued on next page}
2137 \DWLNSadvancepc&0x02 \\
2138 \DWLNSadvanceline&0x03 \\
2139 \DWLNSsetfile&0x04 \\
2140 \DWLNSsetcolumn&0x05 \\
2141 \DWLNSnegatestmt&0x06 \\
2142 \DWLNSsetbasicblock&0x07 \\
2143 \DWLNSconstaddpc&0x08 \\
2144 \DWLNSfixedadvancepc&0x09 \\
2145 \DWLNSsetprologueend&0x0a \\
2146 \DWLNSsetepiloguebegin&0x0b \\
2147 \DWLNSsetisa&0x0c \\
2154 The encodings for the extended opcodes are given in
2155 \addtoindexx{line number opcodes!extended opcode encoding}
2156 Table \refersec{tab:linenumberextendedopcodeencodings}.
2159 \setlength{\extrarowheight}{0.1cm}
2160 \begin{longtable}{l|c}
2161 \caption{Line number extended opcode encodings} \label{tab:linenumberextendedopcodeencodings}\\
2162 \hline \bfseries Opcode name&\bfseries Value \\ \hline
2164 \bfseries Opcode name&\bfseries Value\\ \hline
2166 \hline \emph{Continued on next page}
2171 \DWLNEendsequence&0x01 \\
2172 \DWLNEsetaddress&0x02\\
2173 \DWLNEdefinefile&0x03\\
2174 \DWLNEsetdiscriminator{} &0x04 \\
2175 \DWLNElouser&0x80 \\
2176 \DWLNEhiuser&\xff \\
2181 \section{Macro Information}
2182 \label{datarep:macroinformation}
2184 The source line numbers and source file indices encoded in the
2185 macro information section are represented as unsigned LEB128
2186 numbers as are the constants in a
2187 \DWMACINFOvendorext{} entry.
2189 The macinfo type is encoded as a single byte.
2191 \addtoindexx{macinfo types!encoding}
2193 Table \refersec{tab:macinfotypeencodings}.
2197 \setlength{\extrarowheight}{0.1cm}
2198 \begin{longtable}{l|c}
2199 \caption{Macinfo type encodings} \label{tab:macinfotypeencodings}\\
2200 \hline \bfseries Macinfo Type Name&\bfseries Value \\ \hline
2202 \bfseries Macinfo Type Name&\bfseries Value\\ \hline
2204 \hline \emph{Continued on next page}
2209 \DWMACINFOdefine&0x01 \\
2210 \DWMACINFOundef&0x02 \\
2211 \DWMACINFOstartfile&0x03 \\
2212 \DWMACINFOendfile&0x04 \\
2213 \DWMACINFOvendorext&\xff \\
2219 \section{Call Frame Information}
2220 \label{datarep:callframeinformation}
2222 In the \thirtytwobitdwarfformat, the value of the CIE id in the
2223 CIE header is \xffffffff; in the \sixtyfourbitdwarfformat, the
2224 value is \xffffffffffffffff.
2226 The value of the CIE \addtoindexi{version number}{version number!call frame information}
2227 is 4 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
2229 Call frame instructions are encoded in one or more bytes. The
2230 primary opcode is encoded in the high order two bits of
2231 the first byte (that is, opcode = byte $\gg$ 6). An operand
2232 or extended opcode may be encoded in the low order 6
2233 bits. Additional operands are encoded in subsequent bytes.
2234 The instructions and their encodings are presented in
2235 Table \refersec{tab:callframeinstructionencodings}.
2238 \setlength{\extrarowheight}{0.1cm}
2239 \begin{longtable}{l|c|c|l|l}
2240 \caption{Call frame instruction encodings} \label{tab:callframeinstructionencodings} \\
2241 \hline &\bfseries High 2 &\bfseries Low 6 & & \\
2242 \bfseries Instruction&\bfseries Bits &\bfseries Bits &\bfseries Operand 1 &\bfseries Operand 2\\ \hline
2244 & \bfseries High 2 &\bfseries Low 6 & &\\
2245 \bfseries Instruction&\bfseries Bits &\bfseries Bits &\bfseries Operand 1 &\bfseries Operand 2\\ \hline
2247 \hline \emph{Continued on next page}
2252 \DWCFAadvanceloc&0x1&delta & \\
2253 \DWCFAoffset&0x2®ister&ULEB128 offset \\
2254 \DWCFArestore&0x3®ister & & \\
2255 \DWCFAnop&0&0 & & \\
2256 \DWCFAsetloc&0&0x01&address & \\
2257 \DWCFAadvancelocone&0&0x02&1\dash byte delta & \\
2258 \DWCFAadvanceloctwo&0&0x03&2\dash byte delta & \\
2259 \DWCFAadvancelocfour&0&0x04&4\dash byte delta & \\
2260 \DWCFAoffsetextended&0&0x05&ULEB128 register&ULEB128 offset \\
2261 \DWCFArestoreextended&0&0x06&ULEB128 register & \\
2262 \DWCFAundefined&0&0x07&ULEB128 register & \\
2263 \DWCFAsamevalue&0&0x08 &ULEB128 register & \\
2264 \DWCFAregister&0&0x09&ULEB128 register &ULEB128 offset \\
2265 \DWCFArememberstate&0&0x0a & & \\
2266 \DWCFArestorestate&0&0x0b & & \\
2267 \DWCFAdefcfa&0&0x0c &ULEB128 register&ULEB128 offset \\
2268 \DWCFAdefcfaregister&0&0x0d&ULEB128 register & \\
2269 \DWCFAdefcfaoffset&0&0x0e &ULEB128 offset & \\
2270 \DWCFAdefcfaexpression&0&0x0f &BLOCK \\
2271 \DWCFAexpression&0&0x10&ULEB128 register & BLOCK \\
2273 \DWCFAoffsetextendedsf&0&0x11&ULEB128 register&SLEB128 offset \\
2274 \DWCFAdefcfasf&0&0x12&ULEB128 register&SLEB128 offset \\
2275 \DWCFAdefcfaoffsetsf&0&0x13&SLEB128 offset & \\
2276 \DWCFAvaloffset&0&0x14&ULEB128&ULEB128 \\
2277 \DWCFAvaloffsetsf&0&0x15&ULEB128&SLEB128 \\
2278 \DWCFAvalexpression&0&0x16&ULEB128&BLOCK \\
2279 \DWCFAlouser&0&0x1c & & \\
2280 \DWCFAhiuser&0&\xiiif & & \\
2284 \section{Non-contiguous Address Ranges}
2285 \label{datarep:noncontiguousaddressranges}
2287 Each entry in a \addtoindex{range list}
2288 (see Section \refersec{chap:noncontiguousaddressranges})
2290 \addtoindexx{base address selection entry!in range list}
2292 \addtoindexx{range list}
2293 a base address selection entry, or an end
2296 A \addtoindex{range list} entry consists of two relative addresses. The
2297 addresses are the same size as addresses on the target machine.
2299 A base address selection entry and an
2300 \addtoindexx{end of list entry!in range list}
2301 end of list entry each
2302 \addtoindexx{base address selection entry!in range list}
2303 consist of two (constant or relocated) addresses. The two
2304 addresses are the same size as addresses on the target machine.
2306 For a \addtoindex{range list} to be specified, the base address of the
2307 \addtoindexx{base address selection entry!in range list}
2308 corresponding compilation unit must be defined
2309 (see Section \refersec{chap:normalandpartialcompilationunitentries}).
2312 \section{Dependencies and Constraints}
2313 \label{datarep:dependenciesandconstraints}
2315 The debugging information in this format is intended to
2317 \addtoindexx{DWARF section names!list of}
2319 the \dotdebugabbrev{},
2326 \dotdebugpubnames{},
2327 \dotdebugpubtypes{},
2332 sections of an object file, or equivalent
2333 separate file or database. The information is not
2334 word\dash aligned. Consequently:
2337 \item For the \thirtytwobitdwarfformat{} and a target architecture with
2338 32\dash bit addresses, an assembler or compiler must provide a way
2339 to produce 2\dash byte and 4\dash byte quantities without alignment
2340 restrictions, and the linker must be able to relocate a
2341 4\dash byte address or
2342 \addtoindexx{section offset!alignment of}
2343 section offset that occurs at an arbitrary
2346 \item For the \thirtytwobitdwarfformat{} and a target architecture with
2347 64\dash bit addresses, an assembler or compiler must provide a
2348 way to produce 2\dash byte, 4\dash byte and 8\dash byte quantities without
2349 alignment restrictions, and the linker must be able to relocate
2350 an 8\dash byte address or 4\dash byte
2351 \addtoindexx{section offset!alignment of}
2352 section offset that occurs at an
2353 arbitrary alignment.
2355 \item For the \sixtyfourbitdwarfformat{} and a target architecture with
2356 32\dash bit addresses, an assembler or compiler must provide a
2357 way to produce 2\dash byte, 4\dash byte and 8\dash byte quantities without
2358 alignment restrictions, and the linker must be able to relocate
2359 a 4\dash byte address or 8\dash byte
2360 \addtoindexx{section offset!alignment of}
2361 section offset that occurs at an
2362 arbitrary alignment.
2364 \textit{It is expected that this will be required only for very large
2365 32\dash bit programs or by those architectures which support
2366 a mix of 32\dash bit and 64\dash bit code and data within the same
2369 \item For the \sixtyfourbitdwarfformat{} and a target architecture with
2370 64\dash bit addresses, an assembler or compiler must provide a
2371 way to produce 2\dash byte, 4\dash byte and 8\dash byte quantities without
2372 alignment restrictions, and the linker must be able to
2373 relocate an 8\dash byte address or
2374 \addtoindexx{section offset!alignment of}
2375 section offset that occurs at
2376 an arbitrary alignment.
2379 \section{Integer Representation Names}
2380 \label{datarep:integerrepresentationnames}
2382 The sizes of the integers used in the lookup by name, lookup
2383 by address, line number and call frame information sections
2385 Table \ref{tab:integerrepresentationnames}.
2388 \setlength{\extrarowheight}{0.1cm}
2389 \begin{longtable}{c|l}
2390 \caption{Integer representation names} \label{tab:integerrepresentationnames}\\
2391 \hline \bfseries Representation name&\bfseries Representation \\ \hline
2393 \bfseries Representation name&\bfseries Representation\\ \hline
2395 \hline \emph{Continued on next page}
2400 \addtoindex{sbyte}& signed, 1\dash byte integer \\
2401 \addtoindex{ubyte}&unsigned, 1\dash byte integer \\
2402 \addtoindex{uhalf}&unsigned, 2\dash byte integer \\
2403 \addtoindex{uword}&unsigned, 4\dash byte integer \\
2409 \section{Type Signature Computation}
2410 \label{datarep:typesignaturecomputation}
2412 A type signature is computed only by the DWARF producer;
2413 \addtoindexx{type signature computation}
2414 it is used by a DWARF consumer to resolve type references to
2415 the type definitions that are contained in
2416 \addtoindexx{type unit}
2419 The type signature for a type T0 is formed from the
2420 \addtoindex{MD5 hash}
2421 of a flattened description of the type. The flattened
2422 description of the type is a byte sequence derived from the
2423 DWARF encoding of the type as follows:
2424 \begin{enumerate}[1. ]
2426 \item Start with an empty sequence S and a list V of visited
2427 types, where V is initialized to a list containing the type
2428 T0 as its single element. Elements in V are indexed from 1,
2431 \item If the debugging information entry represents a type that
2432 is nested inside another type or a namespace, append to S
2433 the type\textquoteright s context as follows: For each surrounding type
2434 or namespace, beginning with the outermost such construct,
2435 append the letter 'C', the DWARF tag of the construct, and
2436 the name (taken from
2437 \addtoindexx{name attribute}
2438 the \DWATname{} attribute) of the type
2439 \addtoindexx{name attribute}
2440 or namespace (including its trailing null byte).
2442 \item Append to S the letter 'D', followed by the DWARF tag of
2443 the debugging information entry.
2445 \item For each of the attributes in
2446 Table \refersec{tab:attributesusedintypesignaturecomputation}
2448 the debugging information entry, in the order listed,
2449 append to S a marker letter (see below), the DWARF attribute
2450 code, and the attribute value.
2453 \caption{Attributes used in type signature computation}
2454 \label{tab:attributesusedintypesignaturecomputation}
2455 \simplerule[\textwidth]
2457 \autocols[0pt]{c}{2}{l}{
2472 \DWATcontainingtype,
2476 \DWATdatamemberlocation,
2498 \DWATstringlengthbitsize,
2499 \DWATstringlengthbytesize,
2504 \DWATvariableparameter,
2507 \DWATvtableelemlocation
2510 \simplerule[\textwidth]
2513 Note that except for the initial
2514 \DWATname{} attribute,
2515 \addtoindexx{name attribute}
2516 attributes are appended in order according to the alphabetical
2517 spelling of their identifier.
2519 If an implementation defines any vendor-specific attributes,
2520 any such attributes that are essential to the definition of
2521 the type should also be included at the end of the above list,
2522 in their own alphabetical suborder.
2524 An attribute that refers to another type entry T is processed
2525 as follows: (a) If T is in the list V at some V[x], use the
2526 letter 'R' as the marker and use the unsigned LEB128 encoding
2527 of x as the attribute value; otherwise, (b) use the letter 'T'
2528 as the marker, process the type T recursively by performing
2529 Steps 2 through 7, and use the result as the attribute value.
2531 Other attribute values use the letter 'A' as the marker, and
2532 the value consists of the form code (encoded as an unsigned
2533 LEB128 value) followed by the encoding of the value according
2534 to the form code. To ensure reproducibility of the signature,
2535 the set of forms used in the signature computation is limited
2536 to the following: \DWFORMsdata,
2541 \item If the tag in Step 3 is one of \DWTAGpointertype,
2542 \DWTAGreferencetype,
2543 \DWTAGrvaluereferencetype,
2544 \DWTAGptrtomembertype,
2545 or \DWTAGfriend, and the referenced
2546 type (via the \DWATtype{} or
2547 \DWATfriend{} attribute) has a
2548 \DWATname{} attribute, append to S the letter 'N', the DWARF
2549 attribute code (\DWATtype{} or
2550 \DWATfriend), the context of
2551 the type (according to the method in Step 2), the letter 'E',
2552 and the name of the type. For \DWTAGfriend, if the referenced
2553 entry is a \DWTAGsubprogram, the context is omitted and the
2554 name to be used is the ABI-specific name of the subprogram
2555 (e.g., the mangled linker name).
2558 \item If the tag in Step 3 is not one of \DWTAGpointertype,
2559 \DWTAGreferencetype,
2560 \DWTAGrvaluereferencetype,
2561 \DWTAGptrtomembertype, or
2562 \DWTAGfriend, but has
2563 a \DWATtype{} attribute, or if the referenced type (via
2565 \DWATfriend{} attribute) does not have a
2566 \DWATname{} attribute, the attribute is processed according to
2567 the method in Step 4 for an attribute that refers to another
2571 \item Visit each child C of the debugging information
2572 entry as follows: If C is a nested type entry or a member
2573 function entry, and has
2574 a \DWATname{} attribute, append to
2575 \addtoindexx{name attribute}
2576 S the letter 'S', the tag of C, and its name; otherwise,
2577 process C recursively by performing Steps 3 through 7,
2578 appending the result to S. Following the last child (or if
2579 there are no children), append a zero byte.
2584 For the purposes of this algorithm, if a debugging information
2586 \DWATspecification{}
2587 attribute that refers to
2588 another entry D (which has a
2591 then S inherits the attributes and children of D, and S is
2592 processed as if those attributes and children were present in
2593 the entry S. Exception: if a particular attribute is found in
2594 both S and D, the attribute in S is used and the corresponding
2595 one in D is ignored.
2597 DWARF tag and attribute codes are appended to the sequence
2598 as unsigned LEB128 values, using the values defined earlier
2601 \textit{A grammar describing this computation may be found in
2602 Appendix \refersec{app:typesignaturecomputationgrammar}.
2605 \textit{An attribute that refers to another type entry should
2606 be recursively processed or replaced with the name of the
2607 referent (in Step 4, 5 or 6). If neither treatment applies to
2608 an attribute that references another type entry, the entry
2609 that contains that attribute should not be considered for a
2610 separate \addtoindex{type unit}.}
2612 \textit{If a debugging information entry contains an attribute from
2613 the list above that would require an unsupported form, that
2614 entry should not be considered for a separate
2615 \addtoindex{type unit}.}
2617 \textit{A type should be considered for a separate
2618 \addtoindex{type unit} only
2619 if all of the type entries that it contains or refers to in
2620 Steps 6 and 7 can themselves each be considered for a separate
2621 \addtoindex{type unit}.}
2624 Where the DWARF producer may reasonably choose two or more
2625 different forms for a given attribute, it should choose
2626 the simplest possible form in computing the signature. (For
2627 example, a constant value should be preferred to a location
2628 expression when possible.)
2630 Once the string S has been formed from the DWARF encoding,
2631 an \addtoindex{MD5 hash} is computed for the string and the lower 64 bits
2632 are taken as the type signature.
2634 \textit{The string S is intended to be a flattened representation of
2635 the type that uniquely identifies that type (i.e., a different
2636 type is highly unlikely to produce the same string).}
2638 \textit{A debugging information entry should not be placed in a
2639 separate \addtoindex{type unit}
2640 if any of the following apply:}
2644 \item \textit{The entry has an attribute whose value is a location
2645 expression, and the location expression contains a reference to
2646 another debugging information entry (e.g., a \DWOPcallref{}
2647 operator), as it is unlikely that the entry will remain
2648 identical across compilation units.}
2650 \item \textit{The entry has an attribute whose value refers
2651 to a code location or a \addtoindex{location list}.}
2653 \item \textit{The entry has an attribute whose value refers
2654 to another debugging information entry that does not represent
2660 \textit{Certain attributes are not included in the type signature:}
2663 \item \textit{The \DWATdeclaration{} attribute is not included because it
2664 indicates that the debugging information entry represents an
2665 incomplete declaration, and incomplete declarations should
2667 \addtoindexx{type unit}
2668 separate type units.}
2670 \item \textit{The \DWATdescription{} attribute is not included because
2671 it does not provide any information unique to the defining
2672 declaration of the type.}
2674 \item \textit{The \DWATdeclfile,
2676 \DWATdeclcolumn{} attributes are not included because they
2677 may vary from one source file to the next, and would prevent
2678 two otherwise identical type declarations from producing the
2679 \addtoindexx{MD5 hash}
2682 \item \textit{The \DWATobjectpointer{} attribute is not included
2683 because the information it provides is not necessary for the
2684 computation of a unique type signature.}
2688 \textit{Nested types and some types referred to by a debugging
2689 information entry are encoded by name rather than by recursively
2690 encoding the type to allow for cases where a complete definition
2691 of the type might not be available in all compilation units.}
2693 \textit{If a type definition contains the definition of a member function,
2694 it cannot be moved as is into a type unit, because the member function
2695 contains attributes that are unique to that compilation unit.
2696 Such a type definition can be moved to a type unit by rewriting the DIE tree,
2697 moving the member function declaration into a separate declaration tree,
2698 and replacing the function definition in the type with a non-defining
2699 declaration of the function (as if the function had been defined out of
2702 An example that illustrates the computation of an MD5 hash may be found in
2703 Appendix \refersec{app:usingtypeunits}.