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