5ff442d7f96187c0f6fec0df712620574021d86d
[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
12 To reserve a portion of the DWARF name space and ranges of
13 enumeration values for use for vendor specific extensions,
14 special labels are reserved for tag names, attribute names,
15 base type encodings, location operations, language names,
16 calling conventions and call frame instructions.
17
18 The labels denoting the beginning and end of the reserved
19 value range for vendor specific extensions consist of the
20 appropriate prefix (DW\-\_TAG, DW\-\_AT, DW\-\_END, DW\-\_ATE, DW\-\_OP,
21 DW\-\_LANG, DW\-\_LNE, DW\-\_CC or DW\-\_CFA respectively) followed by
22 \_lo\_user or \_hi\_user. 
23 \textit{For example, for entry tags, the special
24 labels are \livetarg{chap:DWTAGlouser}{DW\-\_TAG\-\_lo\-\_user} and 
25 \livetarg{chap:DWTAGhiuser}{DW\-\_TAG\-\_hi\-\_user}.}
26 Values in the
27 range between prefix\_lo\_user and prefix\_hi\_user inclusive,
28 are reserved for vendor specific extensions. Vendors may
29 use values in this range without conflicting with current or
30 future system\dash defined values. All other values are reserved
31 for use by the system.
32
33 \textit{There may also be codes for vendor specific extensions
34 between the number of standard line number opcodes and
35 the first special line number opcode. However, since the
36 number of standard opcodes varies with the DWARF version,
37 the range for extensions is also version dependent. Thus,
38 DW\-\_LNS\-\_lo\-\_user and DW\-\_LNS\-\_hi\-\_user symbols are not defined.}
39
40 Vendor defined tags, attributes, base type encodings, location
41 atoms, language names, line number actions, calling conventions
42 and call frame instructions, conventionally use the form
43 prefix\_vendor\_id\_name, where vendor\_id is some identifying
44 character sequence chosen so as to avoid conflicts with
45 other vendors.
46
47 To ensure that extensions added by one vendor may be safely
48 ignored by consumers that do not understand those extensions,
49 the following rules should be followed:
50
51 \begin{enumerate}[1.]
52 \item New attributes should be added in such a way that a
53 debugger may recognize the format of a new attribute value
54 without knowing the content of that attribute value.
55
56 \item The semantics of any new attributes should not alter
57 the semantics of previously existing attributes.
58
59 \item The semantics of any new tags should not conflict with
60 the semantics of previously existing tags.
61
62 \item Do not add any new forms of attribute value.
63
64 \end{enumerate}
65
66
67 \section{Reserved Values}
68 \label{datarep:reservedvalues}
69 \subsection{Error Values}
70 \label{datarep:errorvalues}
71
72 As a convenience for consumers of DWARF information, the value
73 0 is reserved in the encodings for attribute names, attribute
74 forms, base type encodings, location operations, languages,
75 line number program opcodes, macro information entries and tag
76 names to represent an error condition or unknown value. DWARF
77 does not specify names for these reserved values, since they
78 do not represent valid encodings for the given type and should
79 not appear in DWARF debugging information.
80
81
82 \subsection{Initial Length Values}
83 \label{datarep:initiallengthvalues}
84
85 An initial length field is one of the length fields that occur
86 at the beginning of those DWARF sections that have a header
87 (.debug\_aranges, .debug\_info, .debug\_types, .debug\_line,
88 .debug\_pubnames, and .debug\_pubtypes) or the length field
89 that occurs at the beginning of the CIE and FDE structures
90 in the .debug\_frame section.
91
92 In an initial length field, the values 0xfffffff0 through
93 0xffffffff are reserved by DWARF to indicate some form of
94 extension relative to DWARF Version 2; such values must not
95 be interpreted as a length field. The use of one such value,
96 0xffffffff, is defined below 
97 (see Section \refersec{datarep:32bitand64bitdwarfformats}); 
98 the use of
99 the other values is reserved for possible future extensions.
100
101
102
103 \section{Executable Objects and Shared Objects} 
104 \label{datarep:executableobjectsandsharedobjects}
105
106 The relocated addresses in the debugging information for an
107 executable object are virtual addresses and the relocated
108 addresses in the debugging information for a shared object
109 are offsets relative to the start of the lowest region of
110 memory loaded from that shared object.
111
112 \textit{This requirement makes the debugging information for
113 shared objects position independent.  Virtual addresses in a
114 shared object may be calculated by adding the offset to the
115 base address at which the object was attached. This offset
116 is available in the run\dash time linker’s data structures.}
117
118
119
120 \section{32-Bit and 64-Bit DWARF Formats}
121 \label{datarep:32bitand64bitdwarfformats}
122
123 There are two closely related file formats. In the 32\dash bit DWARF
124 format, all values that represent lengths of DWARF sections
125 and offsets relative to the beginning of DWARF sections are
126 represented using 32\dash bits. In the 64\dash bit DWARF format, all
127 values that represent lengths of DWARF sections and offsets
128 relative to the beginning of DWARF sections are represented
129 using 64\dash bits. A special convention applies to the initial
130 length field of certain DWARF sections, as well as the CIE and
131 FDE structures, so that the 32\dash bit and 64\dash bit DWARF formats
132 can coexist and be distinguished within a single linked object.
133
134 The differences between the 32\dash\   and 64\dash bit 
135 DWARF formats are
136 detailed in the following:
137
138
139 \begin{enumerate}[1.]
140
141 \item  In the 32\dash bit DWARF format, an initial length field
142 (see Section \refersec{datarep:initiallengthvalues}) 
143 is an unsigned 32\dash bit integer (which
144 must be less than 0xfffffff0); in the 64\dash bit DWARF format,
145 an initial length field is 96 bits in size, and has two parts:
146 \begin{itemize}
147 \item The first 32\dash bits have the value 0xffffffff.
148
149 \item  The following 64\dash bits contain the actual length
150 represented as an unsigned 64\dash bit integer.
151 \end{itemize}
152
153 \textit{This representation allows a DWARF consumer to dynamically
154 detect that a DWARF section contribution is using the 64\dash bit
155 format and to adapt its processing accordingly.}
156
157 \item Section offset and section length fields that occur
158 in the headers of DWARF sections (other than initial length
159 fields) are listed following. In the 32\dash bit DWARF format these
160 are 32\dash bit unsigned integer values; in the 64\dash bit DWARF format,
161 they are 64\dash bit unsigned integer values.
162
163 \begin{center}
164 \begin{tabular}{lll}
165 Section &Name & Role  \\ \hline
166 .debug\_ranges & debug\_info\_offset & offset in .debug\_info \\
167 .debug\_frame/CIE & CIE\_id & CIE distinguished value \\
168 .debug\_frame/FDE & CIE\_pointer & offset in .debug\_frame \\
169 .debug\_info & debug\_abbrev\_offset & offset in .debug\_abbrev \\
170 .debug\_line & header\_length & length of header itself \\
171 .debug\_pubnames & debug\_info\_offset & offset in .debug\_info \\
172                 & debug\_info\_length & length of .debug\_info \\
173                 &                   & contribution \\
174 .debug\_pubtypes & debug\_info\_offset & offset in .debug\_info \\
175                 & debug\_info\_length & length of .debug\_info \\
176                 &                   & contribution \\
177 .debug\_types & debug\_abbrev\_offset & offset in .debug\_info \\
178                 & type\_offset & offset in of .debug\_types \\
179
180 \end{tabular}
181 \end{center}
182
183 \textit{The CIE\_id field in a CIE structure must be 64 bits because
184 it overlays the CIE\_pointer in a FDE structure; this implicit
185 union must be accessed to distinguish whether a CIE or FDE is
186 present, consequently, these two fields must exactly overlay
187 each other (both offset and size).}
188
189 \item Within the body of the .debug\_info or .debug\_types
190 section, certain forms of attribute value depend on the choice
191 of DWARF format as follows. For the 32\dash bit DWARF format,
192 the value is a 32\dash bit unsigned integer; for the 64\dash bit DWARF
193 format, the value is a 64\dash bit unsigned integer.
194 \begin{center}
195 \begin{tabular}{lll}
196 Form & Role  \\ \hline
197 DW\-\_FORM\-\_ref\-\_addr& offset in .debug\_info \\
198 DW\-\_FORM\-\_sec\-\_offset& offset in a section other than .debug\_info or .debug\_str \\
199 DW\-\_FORM\-\_strp&offset in .debug\_str \\
200 DW\-\_OP\-\_call\-\_ref&offset in .debug\_info \\
201 \end{tabular}
202 \end{center}
203
204 \item Within the body of the .debug\_pubnames and
205 .debug\_pubtypes sections, the representation of the first field
206 of each tuple (which represents an offset in the .debug\_info
207 section) depends on the DWARF format as follows: in the
208 32\dash bit DWARF format, this field is a 32\dash bit unsigned integer;
209 in the 64\dash bit DWARF format, it is a 64\dash bit unsigned integer.
210
211 \end{enumerate}
212
213
214 The 32\dash bit and 64\dash bit DWARF format conventions must not be
215 intermixed within a single compilation unit.
216
217 \textit{Attribute values and section header fields that represent
218 addresses in the target program are not affected by these
219 rules.}
220
221 A DWARF consumer that supports the 64\dash bit DWARF format must
222 support executables in which some compilation units use the
223 32\dash bit format and others use the 64\dash bit format provided that
224 the combination links correctly (that is, provided that there
225 are no link\dash time errors due to truncation or overflow). (An
226 implementation is not required to guarantee detection and
227 reporting of all such errors.)
228
229 \textit{It is expected that DWARF producing compilers will not use
230 the 64\dash bit format by default. In most cases, the division of
231 even very large applications into a number of executable and
232 shared objects will suffice to assure that the DWARF sections
233 within each individual linked object are less than 4 GBytes
234 in size. However, for those cases where needed, the 64\dash bit
235 format allows the unusual case to be handled as well. Even
236 in this case, it is expected that only application supplied
237 objects will need to be compiled using the 64\dash bit format;
238 separate 32\dash bit format versions of system supplied shared
239 executable libraries can still be used.}
240
241
242
243 \section{Format of Debugging Information}
244 \label{datarep:formatofdebugginginformation}
245
246 For each compilation unit compiled with a DWARF producer,
247 a contribution is made to the .debug\_info section of
248 the object file. Each such contribution consists of a
249 compilation unit header 
250 (see Section \refersec{datarep:compilationunitheader}) 
251 followed by a
252 single \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} or \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} debugging
253 information entry, together with its children.
254
255 For each type defined in a compilation unit, a contribution may
256 be made to the .debug\_types section of the object file. Each
257 such contribution consists of a type unit header 
258 (see Section \refersec{datarep:typeunitheader}) 
259 followed by a \livelink{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit} entry, together with
260 its children.
261
262 Each debugging information entry begins with a code that
263 represents an entry in a separate abbreviations table. This
264 code is followed directly by a series of attribute values.
265
266 The appropriate entry in the abbreviations table guides the
267 interpretation of the information contained directly in the
268 .debug\_info or .debug\_types section.
269
270 Multiple debugging information entries may share the same
271 abbreviation table entry. Each compilation unit is associated
272 with a particular abbreviation table, but multiple compilation
273 units may share the same table.
274 \subsection{Unit Headers}
275 \label{datarep:unitheaders}
276
277 \subsubsection{Compilation Unit Header}
278 \label{datarep:compilationunitheader}
279
280 \begin{enumerate}[1.]
281
282 \item unit\_length (initial length) \\
283 A 4\dash byte or 12\dash byte unsigned integer representing the length
284 of the .debug\_info contribution for that compilation unit,
285 not including the length field itself. In the 32\dash bit DWARF
286 format, this is a 4\dash byte unsigned integer (which must be less
287 than 0xfffffff0); in the 64\dash bit DWARF format, this consists
288 of the 4\dash byte value 0xffffffff followed by an 8\dash byte unsigned
289 integer that gives the actual length 
290 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
291
292 \item  version (uhalf)
293 A 2\dash byte unsigned integer representing the version of the
294 DWARF information for the compilation unit 
295 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
296 The value in this field is 4.
297
298 \item debug\_abbrev\_offset (section offset) \\
299 A 4\dash byte or 8\dash byte unsigned offset into the .debug\_abbrev
300 section. This offset associates the compilation unit with a
301 particular set of debugging information entry abbreviations. In
302 the 32\dash bit DWARF format, this is a 4\dash byte unsigned length;
303 in the 64\dash bit DWARF format, this is an 8\dash byte unsigned length
304 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
305
306 \item address\_size (ubyte) \\
307 A 1\dash byte unsigned integer representing the size in bytes of
308 an address on the target architecture. If the system uses
309 segmented addressing, this value represents the size of the
310 offset portion of an address.
311
312
313
314
315 \end{enumerate}
316
317 \subsubsection{Type Unit Header}
318 \label{datarep:typeunitheader}
319
320 The header for the series of debugging information entries
321 contributing to the description of a type that has been
322 placed in its own type unit, within the .debug\_types section,
323 consists of the following information:
324
325 \begin{enumerate}[1.]
326
327 \item unit\_length (initial length) \\
328 A 4\dash byte or 12\dash byte unsigned integer representing the length
329 of the .debug\_types contribution for that compilation unit,
330 not including the length field itself. In the 32\dash bit DWARF
331 format, this is a 4\dash byte unsigned integer (which must be
332 less than 0xfffffff0); in the 64\dash bit DWARF format, this
333 consists of the 4\dash byte value 0xffffffff followed by an 
334 8\dash byte unsigned integer that gives the actual length
335 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
336
337 \item  version (uhalf)
338 A 2\dash byte unsigned integer representing the version of the
339 DWARF information for the compilation unit 
340 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
341 The value in this field is 4.
342
343 \item debug\_abbrev\_offset (section offset) \\
344 A 4\dash byte or 8\dash byte unsigned offset into the .debug\_abbrev
345 section. This offset associates the compilation unit with a
346 particular set of debugging information entry abbreviations. In
347 the 32\dash bit DWARF format, this is a 4\dash byte unsigned length;
348 in the 64\dash bit DWARF format, this is an 8\dash byte unsigned length
349 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
350
351 \item address\_size (ubyte) \\
352 A 1\dash byte unsigned integer representing the size in bytes of
353 an address on the target architecture. If the system uses
354 segmented addressing, this value represents the size of the
355 offset portion of an address.
356
357
358 \item type\_signature (8\dash byte unsigned integer) \\
359 A 64\dash bit unique signature of the type described in this type
360 unit.  
361
362 \textit{An attribute that refers(using DW\-\_FORM\-\_ref\-\_sig8) to
363 the primary type contained in this type unit uses this value.}
364
365
366 \item type\_offset (section offset) \\
367 A 4\dash byte or 8\dash byte unsigned offset relative to the beginning
368 of the type unit header. This offset refers to the debugging
369 information entry that describes the type. Because the type
370 may be nested inside a namespace or other structures, and may
371 contain references to other types that have not been placed in
372 separate type units, it is not necessarily either the first or
373 the only entry in the type unit. In the 32\dash bit DWARF format,
374 this is a 4\dash byte unsigned length; in the 64\dash bit DWARF format,
375 this is an 8\dash byte unsigned length
376 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
377
378 \end{enumerate}
379
380 \subsection{Debugging Information Entry}
381 \label{datarep:debugginginformationentry}
382
383 Each debugging information entry begins with an unsigned LEB128
384 number containing the abbreviation code for the entry. This
385 code represents an entry within the abbreviations table
386 associated with the compilation unit containing this entry. The
387 abbreviation code is followed by a series of attribute values.
388
389 On some architectures, there are alignment constraints on
390 section boundaries. To make it easier to pad debugging
391 information sections to satisfy such constraints, the
392 abbreviation code 0 is reserved. Debugging information entries
393 consisting of only the abbreviation code 0 are considered
394 null entries.
395
396 \subsection{Abbreviations Tables}
397 \label{datarep:abbreviationstables}
398
399 The abbreviations tables for all compilation units
400 are contained in a separate object file section called
401 .debug\_abbrev. As mentioned before, multiple compilation
402 units may share the same abbreviations table.
403
404 The abbreviations table for a single compilation unit consists
405 of a series of abbreviation declarations. Each declaration
406 specifies the tag and attributes for a particular form of
407 debugging information entry. Each declaration begins with
408 an unsigned LEB128 number representing the abbreviation
409 code itself. It is this code that appears at the beginning
410 of a debugging information entry in the .debug\_info or
411 .debug\_types section. As described above, the abbreviation
412 code 0 is reserved for null debugging information entries. The
413 abbreviation code is followed by another unsigned LEB128
414 number that encodes the entry’s tag. The encodings for the
415 tag names are given in 
416 Table \refersec{tab:tagencodings}.
417
418 Following the tag encoding is a 1\dash byte value that determines
419 whether a debugging information entry using this abbreviation
420 has child entries or not. If the value is DW\-\_CHILDREN\-\_yes,
421 the next physically succeeding entry of any debugging
422 information entry using this abbreviation is the first
423 child of that entry. If the 1\dash byte value following the
424 abbreviation’s tag encoding is DW\-\_CHILDREN\-\_no, the next
425 physically succeeding entry of any debugging information entry
426 using this abbreviation is a sibling of that entry. (Either
427 the first child or sibling entries may be null entries). The
428 encodings for the child determination byte are given in 
429 Table \refersec{tab:childdeterminationencodings}
430 (As mentioned in 
431 Section \refersec{chap:relationshipofdebugginginformationentries}, 
432 each chain of
433 sibling entries is terminated by a null entry.)
434
435 Finally, the child encoding is followed by a series of
436 attribute specifications. Each attribute specification
437 consists of two parts. The first part is an unsigned LEB128
438 number representing the attribute’s name. The second part
439 is an unsigned LEB128 number representing the attribute’s
440 form. The series of attribute specifications ends with an
441 entry containing 0 for the name and 0 for the form.
442
443 The attribute form DW\-\_FORM\-\_indirect is a special case. For
444 attributes with this form, the attribute value itself in the
445 .debug\_info or .debug\_types section begins with an unsigned
446 LEB128 number that represents its form. This allows producers
447 to choose forms for particular attributes dynamically,
448 without having to add a new entry to the abbreviations table.
449
450 The abbreviations for a given compilation unit end with an
451 entry consisting of a 0 byte for the abbreviation code.
452
453 See 
454 Appendix \refersec{app:compilationunitsandabbreviationstableexample} 
455 for a depiction of the organization of the
456 debugging information.
457
458 \subsection{Attribute Encodings}
459 \label{datarep:attributeencodings}
460
461 The encodings for the attribute names are given in 
462 Table \refersec{tab:attributeencodings}.
463
464 The attribute form governs how the value of the attribute is
465 encoded. There are nine classes of form, listed below. Each
466 class is a set of forms which have related representations
467 and which are given a common interpretation according to the
468 attribute in which the form is used.
469
470 Form DW\-\_FORM\-\_sec\-\_offset is a member of more than one class,
471 namely \livelink{chap:lineptr}{lineptr}, \livelink{chap:loclistptr}{loclistptr}, \livelink{chap:macptr}{macptr} or \livelink{chap:rangelistptr}{rangelistptr}; the list
472 of classes allowed by the applicable attribute in 
473 Table \refersec{tab:attributeencodings}
474 determines the class of the form.
475
476 \textit{In DWARF V3 the forms DW\-\_FORM\-\_data4 and DW\-\_FORM\-\_data8 were
477 members of either class constant or one of the classes \livelink{chap:lineptr}{lineptr},
478 \livelink{chap:loclistptr}{loclistptr}, \livelink{chap:macptr}{macptr} or \livelink{chap:rangelistptr}{rangelistptr}, depending on context. In
479 DWARF V4 DW\-\_FORM\-\_data4 and DW\-\_FORM\-\_data8 are members of class
480 constant in all cases. The new DW\-\_FORM\-\_sec\-\_offset replaces
481 their usage for the other classes.}
482
483 Each possible form belongs to one or more of the following classes:
484
485 \begin{itemize}
486 \item address \\
487 Represented as an object of appropriate size to hold an
488 address on the target machine (DW\-\_FORM\-\_addr). The size is
489 encoded in the compilation unit header 
490 (see Section \refersec{datarep:compilationunitheader}).
491 This address is relocatable in a relocatable object file and
492 is relocated in an executable file or shared object.
493
494 \item block \\
495 Blocks come in four forms:
496
497 \begin{myindentpara}{1cm}
498 A 1\dash byte length followed by 0 to 255 contiguous information
499 bytes (DW\-\_FORM\-\_block1).
500 \end{myindentpara}
501
502 \begin{myindentpara}{1cm}
503 A 2\dash byte length followed by 0 to 65,535 contiguous information
504 bytes (DW\-\_FORM\-\_block2).
505 \end{myindentpara}
506
507
508 \begin{myindentpara}{1cm}
509 A 4\dash byte length followed by 0 to 4,294,967,295 contiguous
510 information bytes (DW\-\_FORM\-\_block4).
511 \end{myindentpara}
512
513
514 \begin{myindentpara}{1cm}
515 An unsigned LEB128 length followed by the number of bytes
516 specified by the length (DW\-\_FORM\-\_block).
517 \end{myindentpara}
518
519 In all forms, the length is the number of information bytes
520 that follow. The information bytes may contain any mixture
521 of relocated (or relocatable) addresses, references to other
522 debugging information entries or data bytes.
523
524 \item constant \\
525 There are six forms of constants. There are fixed length
526 constant data forms for one, two, four and eight byte values
527 (respectively, DW\-\_FORM\-\_data1, DW\-\_FORM\-\_data2, DW\-\_FORM\-\_data4,
528 and DW\-\_FORM\-\_data8). There are also variable length constant
529 data forms encoded using LEB128 numbers (see below). Both
530 signed (DW\-\_FORM\-\_sdata) and unsigned (DW\-\_FORM\-\_udata) variable
531 length constants are available
532
533 The data in DW\-\_FORM\-\_data1, DW\-\_FORM\-\_data2, DW\-\_FORM\-\_data4 and
534 DW\-\_FORM\-\_data8 can be anything. Depending on context, it may
535 be a signed integer, an unsigned integer, a floating\dash point
536 constant, or anything else. A consumer must use context to
537 know how to interpret the bits, which if they are target
538 machine data (such as an integer or floating point constant)
539 will be in target machine byte\dash order.
540
541 \textit{If one of the DW\-\_FORM\-\_data<n> forms is used to represent a
542 signed or unsigned integer, it can be hard for a consumer
543 to discover the context necessary to determine which
544 interpretation is intended. Producers are therefore strongly
545 encouraged to use DW\-\_FORM\-\_sdata or DW\-\_FORM\-\_udata for signed and
546 unsigned integers respectively, rather than 
547 DW\-\_FORM\-\_data\textless n \textgreater.}
548
549
550 \item \livelink{chap:exprloc}{exprloc} \\
551 This is an unsigned LEB128 length followed by the
552 number of information bytes specified by the length
553 (DW\-\_FORM\-\_exprloc). The information bytes contain a DWARF
554 expression 
555 (see Section \refersec{chap:dwarfexpressions}) 
556 or location description 
557 (see Section \refersec{chap:locationdescriptions}).
558
559 \item flag \\
560 A flag is represented explicitly as a single byte of data
561 (DW\-\_FORM\-\_flag) or implicitly (DW\-\_FORM\-\_flag\-\_present). In the
562 first case, if the flag has value zero, it indicates the
563 absence of the attribute; if the flag has a non\dash zero value,
564 it indicates the presence of the attribute. In the second
565 case, the attribute is implicitly indicated as present, and
566 no value is encoded in the debugging information entry itself.
567
568 \item \livelink{chap:lineptr}{lineptr} \\
569 This is an offset into the .debug\_line section
570 (DW\-\_FORM\-\_sec\-\_offset). It consists of an offset from the
571 beginning of the .debug\_line section to the first byte of
572 the data making up the line number list for the compilation
573 unit. 
574 It is relocatable in a relocatable object file, and
575 relocated in an executable or shared object. In the 32\dash bit
576 DWARF format, this offset is a 4\dash byte unsigned value;
577 in the 64\dash bit DWARF format, it is an 8\dash byte unsigned value
578 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
579
580
581 \item \livelink{chap:loclistptr}{loclistptr} \\
582 This is an offset into the .debug\_loc section
583 (DW\-\_FORM\-\_sec\-\_offset). It consists of an offset from the
584 beginning of the .debug\_loc section to the first byte of
585 the data making up the location list for the compilation
586 unit. 
587 It is relocatable in a relocatable object file, and
588 relocated in an executable or shared object. In the 32\dash bit
589 DWARF format, this offset is a 4\dash byte unsigned value;
590 in the 64\dash bit DWARF format, it is an 8\dash byte unsigned value
591 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
592
593
594 \item \livelink{chap:macptr}{macptr} \\
595 This is an offset into the .debug\_macinfo section
596 (DW\-\_FORM\-\_sec\-\_offset). It consists of an offset from the
597 beginning of the .debug\_macinfo section to the first byte of
598 the data making up the macro information list for the compilation
599 unit. 
600 It is relocatable in a relocatable object file, and
601 relocated in an executable or shared object. In the 32\dash bit
602 DWARF format, this offset is a 4\dash byte unsigned value;
603 in the 64\dash bit DWARF format, it is an 8\dash byte unsigned value
604 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
605
606 \item \livelink{chap:rangelistptr}{rangelistptr} \\
607 This is an offset into the .debug\_ranges section
608 (DW\-\_FORM\-\_sec\-\_offset). 
609 It consists of an
610 offset from the beginning of the .debug\_ranges section
611 to the beginning of the non\dash contiguous address ranges
612 information for the referencing entity.  
613 It is relocatable in
614 a relocatable object file, and relocated in an executable or
615 shared object. In the 32\dash bit DWARF format, this offset
616 is a 4\dash byte unsigned value; in the 64\dash bit DWARF
617 format, it is an 8\dash byte unsigned value (see Section
618 \refersec{datarep:32bitand64bitdwarfformats}).
619 \end{itemize}
620
621 \textit{Because classes \livelink{chap:lineptr}{lineptr}, \livelink{chap:loclistptr}{loclistptr}, \livelink{chap:macptr}{macptr} and \livelink{chap:rangelistptr}{rangelistptr}
622 share a common representation, it is not possible for an
623 attribute to allow more than one of these classes}
624
625
626 \begin{itemize}
627 \item reference \\
628 There are three types of reference.
629
630 The first type of reference can identify any debugging
631 information entry within the containing unit. This type of
632 reference is an offset from the first byte of the compilation
633 header for the compilation unit containing the reference. There
634 are five forms for this type of reference. There are fixed
635 length forms for one, two, four and eight byte offsets
636 (respectively, DW\-\_FORM\-\_ref1, DW\-\_FORM\-\_ref2, DW\-\_FORM\-\_ref4,
637 and DW\-\_FORM\-\_ref8). There is also an unsigned variable
638 length offset encoded form that uses unsigned LEB128 numbers
639 (DW\-\_FORM\-\_ref\-\_udata). Because this type of reference is within
640 the containing compilation unit no relocation of the value
641 is required.
642
643 The second type of reference can identify any debugging
644 information entry within a .debug\_info section; in particular,
645 it may refer to an entry in a different compilation unit
646 from the unit containing the reference, and may refer to an
647 entry in a different shared object.  This type of reference
648 (DW\-\_FORM\-\_ref\-\_addr) is an offset from the beginning of the
649 .debug\_info section of the target executable or shared object;
650 it is relocatable in a relocatable object file and frequently
651 relocated in an executable file or shared object. For
652 references from one shared object or static executable file
653 to another, the relocation and identification of the target
654 object must be performed by the consumer. In the 32\dash bit DWARF
655 format, this offset is a 4\dash byte unsigned value; 
656 in the 64\dash bit DWARF format, it is an 8\dash byte
657 unsigned value 
658 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
659
660 A debugging information entry that may be referenced by
661 another compilation unit using DW\-\_FORM\-\_ref\-\_addr must have a
662 global symbolic name.
663
664 For a reference from one executable or shared object to
665 another, the reference is resolved by the debugger to identify
666 the shared object or executable and the offset into that
667 object’s .debug\_info section in the same fashion as the run
668 time loader, either when the debug information is first read,
669 or when the reference is used.
670
671 The third type of reference can identify any debugging
672 information type entry that has been placed in its own
673 type unit. This type of reference (DW\-\_FORM\-\_ref\-\_sig8) is the
674 64\dash bit type signature 
675 (see Section \refersec{datarep:typesignaturecomputation}) 
676 that was computed
677 for the type.
678
679 The use of compilation unit relative references will reduce the
680 number of link\dash time relocations and so speed up linking. The
681 use of the second and third type of reference allows for the
682 sharing of information, such as types, across compilation
683 units.
684
685 A reference to any kind of compilation unit identifies the
686 debugging information entry for that unit, not the preceding
687 header.
688
689 \item string \\
690 A string is a sequence of contiguous non\dash null bytes followed by
691 one null byte. A string may be represented immediately in the
692 debugging information entry itself (DW\-\_FORM\-\_string), or may
693 be represented as an offset into a string table contained in
694 the .debug\_str section of the object file (DW\-\_FORM\-\_strp). In
695 the 32\dash bit DWARF format, the representation of a DW\-\_FORM\-\_strp
696 value is a 4\dash byte unsigned offset; in the 64\dash bit DWARF format,
697 it is an 8\dash byte unsigned offset 
698 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
699
700 If the DW\-\_AT\-\_use\-\_UTF8 attribute is specified for the
701 compilation unit entry, string values are encoded using the
702 UTF\dash 8 (Unicode Transformation Format\dash 8) from the Universal
703 Character Set standard (ISO/IEC 10646\dash 1:1993). Otherwise,
704 the string representation is unspecified.
705
706 The Unicode Standard Version 3 is fully compatible with
707 ISO/IEC 10646\dash 1:1993. It contains all the same characters
708 and encoding points as ISO/IEC 10646, as well as additional
709 information about the characters and their use.
710
711 Earlier versions of DWARF did not specify the representation
712 of strings; for compatibility, this version also does
713 not. However, the UTF\dash 8 representation is strongly recommended.
714
715 \end{itemize}
716
717 In no case does an attribute use one of the classes \livelink{chap:lineptr}{lineptr},
718 \livelink{chap:loclistptr}{loclistptr}, \livelink{chap:macptr}{macptr} or \livelink{chap:rangelistptr}{rangelistptr} to point into either the
719 .debug\_info or .debug\_str section.
720
721 The form encodings are listed in 
722 Table \refersec{tab:attributeformencodings}.
723
724 \begin{centering}
725 \setlength{\extrarowheight}{0.1cm}
726 \begin{longtable}{l|l}
727   \caption{Tag encodings} \label{tab:tagencodings} \\
728   \hline \\ \bfseries Tag name&\bfseries Value\\ \hline
729 \endfirsthead
730   \bfseries Tag name&\bfseries Value \\ \hline
731 \endhead
732   \hline \emph{Continued on next page}
733 \endfoot
734   \hline
735 \endlastfoot
736 \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type} &0x01 \\
737 \livelink{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type}&0x02 \\
738 \livelink{chap:DWTAGentrypoint}{DW\-\_TAG\-\_entry\-\_point}&0x03 \\
739 \livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type}&0x04 \\
740 \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}&0x05 \\
741 \livelink{chap:DWTAGimporteddeclaration}{DW\-\_TAG\-\_imported\-\_declaration}&0x08 \\
742 \livelink{chap:DWTAGlabel}{DW\-\_TAG\-\_label}&0x0a \\
743 \livelink{chap:DWTAGlexicalblock}{DW\-\_TAG\-\_lexical\-\_block}&0x0b \\
744 \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}&0x0d \\
745 \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}&0x0f \\
746 \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type}&0x10 \\
747 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}&0x11 \\
748 \livelink{chap:DWTAGstringtype}{DW\-\_TAG\-\_string\-\_type}&0x12 \\
749 \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}&0x13 \\
750 \livelink{chap:DWTAGsubroutinetype}{DW\-\_TAG\-\_subroutine\-\_type}&0x15 \\
751 \livelink{chap:DWTAGtypedef}{DW\-\_TAG\-\_typedef}&0x16 \\
752 \livelink{chap:DWTAGuniontype}{DW\-\_TAG\-\_union\-\_type}&0x17 \\
753 \livelink{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters}&0x18  \\
754 \livelink{chap:DWTAGvariant}{DW\-\_TAG\-\_variant}&0x19  \\
755 \livelink{chap:DWTAGcommonblock}{DW\-\_TAG\-\_common\-\_block}&0x1a  \\
756 \livelink{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion}&0x1b  \\
757 \livelink{chap:DWTAGinheritance}{DW\-\_TAG\-\_inheritance}&0x1c  \\
758 \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}&0x1d  \\
759 \livelink{chap:DWTAGmodule}{DW\-\_TAG\-\_module}&0x1e  \\
760 \livelink{chap:DWTAGptrtomembertype}{DW\-\_TAG\-\_ptr\-\_to\-\_member\-\_type}&0x1f  \\
761 \livelink{chap:DWTAGsettype}{DW\-\_TAG\-\_set\-\_type}&0x20  \\
762 \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}&0x21  \\
763 \livelink{chap:DWTAGwithstmt}{DW\-\_TAG\-\_with\-\_stmt}&0x22  \\
764 \livelink{chap:DWTAGaccessdeclaration}{DW\-\_TAG\-\_access\-\_declaration}&0x23  \\
765 \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}&0x24  \\
766 \livelink{chap:DWTAGcatchblock}{DW\-\_TAG\-\_catch\-\_block}&0x25  \\
767 \livelink{chap:DWTAGconsttype}{DW\-\_TAG\-\_const\-\_type}&0x26  \\
768 \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant}&0x27  \\
769 \livelink{chap:DWTAGenumerator}{DW\-\_TAG\-\_enumerator}&0x28  \\
770 \livelink{chap:DWTAGfiletype}{DW\-\_TAG\-\_file\-\_type}&0x29  \\
771 \livelink{chap:DWTAGfriend}{DW\-\_TAG\-\_friend}&0x2a  \\
772 \livelink{chap:DWTAGnamelist}{DW\-\_TAG\-\_namelist}&0x2b    \\
773 \livelink{chap:DWTAGnamelistitem}{DW\-\_TAG\-\_namelist\-\_item}&0x2c    \\
774 \livelink{chap:DWTAGpackedtype}{DW\-\_TAG\-\_packed\-\_type}&0x2d    \\
775 \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}&0x2e    \\
776 \livelink{chap:DWTAGtemplatetypeparameter}{DW\-\_TAG\-\_template\-\_type\-\_parameter}&0x2f    \\
777 \livelink{chap:DWTAGtemplatevalueparameter}{DW\-\_TAG\-\_template\-\_value\-\_parameter}&0x30    \\
778 \livelink{chap:DWTAGthrowntype}{DW\-\_TAG\-\_thrown\-\_type}&0x31    \\
779 \livelink{chap:DWTAGtryblock}{DW\-\_TAG\-\_try\-\_block}&0x32    \\
780 \livelink{chap:DWTAGvariantpart}{DW\-\_TAG\-\_variant\-\_part}&0x33    \\
781 \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}&0x34    \\
782 \livelink{chap:DWTAGvolatiletype}{DW\-\_TAG\-\_volatile\-\_type}&0x35    \\
783 \livelink{chap:DWTAGdwarfprocedure}{DW\-\_TAG\-\_dwarf\-\_procedure}&0x36     \\
784 \livelink{chap:DWTAGrestricttype}{DW\-\_TAG\-\_restrict\-\_type}&0x37      \\
785 \livelink{chap:DWTAGinterfacetype}{DW\-\_TAG\-\_interface\-\_type}&0x38      \\
786 \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}&0x39      \\
787 \livelink{chap:DWTAGimportedmodule}{DW\-\_TAG\-\_imported\-\_module}&0x3a      \\
788 \livelink{chap:DWTAGunspecifiedtype}{DW\-\_TAG\-\_unspecified\-\_type}&0x3b      \\
789 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}&0x3c      \\
790 \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}&0x3d      \\
791 \livelink{chap:DWTAGcondition}{DW\-\_TAG\-\_condition}&0x3f      \\
792 \livelink{chap:DWTAGsharedtype}{DW\-\_TAG\-\_shared\-\_type}&0x40      \\
793 \livelink{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit} \ddag &0x41      \\
794 \livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type} \ddag &0x42      \\
795 \livelink{chap:DWTAGtemplatealias}{DW\-\_TAG\-\_template\-\_alias} \ddag &0x43      \\
796 \livelink{chap:DWTAGlouser}{DW\-\_TAG\-\_lo\-\_user}&0x4080      \\
797 \livelink{chap:DWTAGhiuser}{DW\-\_TAG\-\_hi\-\_user}&0xffff      \\
798 \end{longtable}
799 \ddag  TAG new in DWARF Version 4 
800 \end{centering}
801
802
803 \begin{figure}[here]
804 \centering
805 \setlength{\extrarowheight}{0.1cm}
806 \caption{Child determination encodings}
807 \label{tab:childdeterminationencodings}
808 \begin{tabular}{l|l} \hline
809 Child determination name& Value\\ \hline
810 DW\-\_CHILDREN\-\_no&0x00 \\ 
811 DW\-\_CHILDREN\-\_yes&0x01 \\ \hline
812 \end{tabular}
813 \end{figure}
814
815
816 \begin{centering}
817 \setlength{\extrarowheight}{0.1cm}
818 \begin{longtable}{l|l|l}
819   \caption{Attribute encodings} \label{tab:attributeencodings} \\
820   \hline \\ \bfseries Attribute name&\bfseries Value &\bfseries Classes \\ \hline
821 \endfirsthead
822   \bfseries Attribute name&\bfseries Value &\bfseries Classes\\ \hline
823 \endhead
824   \hline \emph{Continued on next page}
825 \endfoot
826   \hline
827 \endlastfoot
828 DW\-\_AT\-\_sibling&0x01&reference \\
829 DW\-\_AT\-\_location&0x02&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}   \\
830 DW\-\_AT\-\_name&0x03&string   \\
831 DW\-\_AT\-\_ordering&0x09&constant   \\
832 DW\-\_AT\-\_byte\-\_size&0x0b&constant, \livelink{chap:exprloc}{exprloc}, reference   \\
833 DW\-\_AT\-\_bit\-\_offset&0x0c&constant, \livelink{chap:exprloc}{exprloc}, reference   \\
834 DW\-\_AT\-\_bit\-\_size&0x0d&constant, \livelink{chap:exprloc}{exprloc}, reference   \\
835 DW\-\_AT\-\_stmt\-\_list&0x10&\livelink{chap:lineptr}{lineptr}   \\
836 DW\-\_AT\-\_low\-\_pc&0x11&address   \\
837 DW\-\_AT\-\_high\-\_pc&0x12&address, constant   \\
838 DW\-\_AT\-\_language&0x13&constant   \\
839 DW\-\_AT\-\_discr&0x15&reference   \\
840 DW\-\_AT\-\_discr\-\_value&0x16&constant   \\
841 DW\-\_AT\-\_visibility&0x17&constant   \\
842 DW\-\_AT\-\_import&0x18&reference   \\
843 DW\-\_AT\-\_string\-\_length&0x19&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}   \\
844 DW\-\_AT\-\_common\-\_reference&0x1a&reference   \\
845 DW\-\_AT\-\_comp\-\_dir&0x1b&string   \\
846 DW\-\_AT\-\_const\-\_value&0x1c&block, constant, string   \\
847 DW\-\_AT\-\_containing\-\_type&0x1d&reference     \\
848 DW\-\_AT\-\_default\-\_value&0x1e&reference     \\
849 DW\-\_AT\-\_inline&0x20&constant     \\
850 DW\-\_AT\-\_is\-\_optional&0x21&flag     \\
851 DW\-\_AT\-\_lower\-\_bound&0x22&constant, \livelink{chap:exprloc}{exprloc}, reference     \\
852 DW\-\_AT\-\_producer&0x25&string     \\
853 DW\-\_AT\-\_prototyped&0x27&flag     \\
854 DW\-\_AT\-\_return\-\_addr&0x2a&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}     \\
855 % FIXME: lower case , not Constant
856 DW\-\_AT\-\_start\-\_scope&0x2c&Constant, \livelink{chap:rangelistptr}{rangelistptr}     \\
857 DW\-\_AT\-\_bit\-\_stride&0x2e&constant, \livelink{chap:exprloc}{exprloc}, reference     \\
858 DW\-\_AT\-\_upper\-\_bound&0x2f&constant, \livelink{chap:exprloc}{exprloc}, reference     \\
859 DW\-\_AT\-\_abstract\-\_origin&0x31&reference     \\
860 DW\-\_AT\-\_accessibility&0x32&constant     \\
861 DW\-\_AT\-\_address\-\_class&0x33&constant     \\
862 DW\-\_AT\-\_artificial&0x34&flag     \\
863 DW\-\_AT\-\_base\-\_types&0x35&reference     \\
864 DW\-\_AT\-\_calling\-\_convention&0x36&constant     \\
865 DW\-\_AT\-\_count&0x37&constant, \livelink{chap:exprloc}{exprloc}, reference     \\
866 DW\-\_AT\-\_data\-\_member\-\_location&0x38&constant, \livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}     \\
867 DW\-\_AT\-\_decl\-\_column&0x39&constant     \\
868 DW\-\_AT\-\_decl\-\_file&0x3a&constant     \\
869 DW\-\_AT\-\_decl\-\_line&0x3b&constant     \\
870 DW\-\_AT\-\_declaration&0x3c&flag     \\
871 DW\-\_AT\-\_discr\-\_list&0x3d&block     \\
872 DW\-\_AT\-\_encoding&0x3e&constant     \\
873 DW\-\_AT\-\_external&0x3f&flag     \\
874 DW\-\_AT\-\_frame\-\_base&0x40&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}     \\
875 DW\-\_AT\-\_friend&0x41&reference     \\
876 DW\-\_AT\-\_identifier\-\_case&0x42&constant    \\
877 DW\-\_AT\-\_macro\-\_info&0x43&\livelink{chap:macptr}{macptr}    \\
878 DW\-\_AT\-\_namelist\-\_item&0x44&reference    \\
879 DW\-\_AT\-\_priority&0x45&reference    \\
880 DW\-\_AT\-\_segment&0x46&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}    \\
881 DW\-\_AT\-\_specification&0x47&reference    \\
882 DW\-\_AT\-\_static\-\_link&0x48&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}    \\
883 DW\-\_AT\-\_type&0x49&reference    \\
884 DW\-\_AT\-\_use\-\_location&0x4a&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}    \\
885 DW\-\_AT\-\_variable\-\_parameter&0x4b&flag    \\
886 DW\-\_AT\-\_virtuality&0x4c&constant    \\
887 DW\-\_AT\-\_vtable\-\_elem\-\_location&0x4d&\livelink{chap:exprloc}{exprloc}, \livelink{chap:loclistptr}{loclistptr}    \\
888
889
890 DW\-\_AT\-\_allocated&0x4e&constant, \livelink{chap:exprloc}{exprloc}, reference     \\
891 DW\-\_AT\-\_associated&0x4f&constant, \livelink{chap:exprloc}{exprloc}, reference     \\
892 DW\-\_AT\-\_data\-\_location&0x50&\livelink{chap:exprloc}{exprloc}     \\
893 DW\-\_AT\-\_byte\-\_stride&0x51&constant, \livelink{chap:exprloc}{exprloc}, reference     \\
894 DW\-\_AT\-\_entry\-\_pc&0x52&address     \\
895 DW\-\_AT\-\_use\-\_UTF8&0x53&flag     \\
896 DW\-\_AT\-\_extension&0x54&reference     \\
897 DW\-\_AT\-\_ranges&0x55&\livelink{chap:rangelistptr}{rangelistptr}     \\
898 DW\-\_AT\-\_trampoline&0x56&address, flag, reference, string     \\
899 DW\-\_AT\-\_call\-\_column&0x57&constant     \\
900 DW\-\_AT\-\_call\-\_file&0x58&constant     \\
901 DW\-\_AT\-\_call\-\_line&0x59&constant     \\
902 DW\-\_AT\-\_description&0x5a&string     \\
903 DW\-\_AT\-\_binary\-\_scale&0x5b&constant     \\
904 DW\-\_AT\-\_decimal\-\_scale&0x5c&constant     \\
905 DW\-\_AT\-\_small &0x5d&reference     \\
906 DW\-\_AT\-\_decimal\-\_sign&0x5e&constant     \\
907 DW\-\_AT\-\_digit\-\_count&0x5f&constant     \\
908 DW\-\_AT\-\_picture\-\_string&0x60&string      \\
909 DW\-\_AT\-\_mutable&0x61&flag     \\
910
911
912 DW\-\_AT\-\_threads\-\_scaled&0x62&flag     \\
913 DW\-\_AT\-\_explicit&0x63&flag     \\
914 DW\-\_AT\-\_object\-\_pointer&0x64&reference     \\
915 DW\-\_AT\-\_endianity&0x65&constant     \\
916 DW\-\_AT\-\_elemental&0x66&flag     \\
917 DW\-\_AT\-\_pure&0x67&flag     \\
918 DW\-\_AT\-\_recursive&0x68&flag     \\
919 DW\-\_AT\-\_signature \ddag &0x69&reference     \\ 
920 DW\-\_AT\-\_main\-\_subprogram \ddag &0x6a&flag     \\
921 DW\-\_AT\-\_data\-\_bit\-\_offset \ddag &0x6b&constant     \\
922 DW\-\_AT\-\_const\-\_expr \ddag &0x6c&flag     \\
923 DW\-\_AT\-\_enum\-\_class \ddag &0x6d&flag     \\
924 DW\-\_AT\-\_linkage\-\_name \ddag &0x6e&string     \\
925 DW\-\_AT\-\_lo\-\_user&0x2000 & ---     \\
926 DW\-\_AT\-\_hi\-\_user&0x3fff& ---     \\
927
928 \end{longtable}
929 \ddag  Attribute new in DWARF Version 4 
930 \end{centering}
931
932 \begin{centering}
933 \setlength{\extrarowheight}{0.1cm}
934 \begin{longtable}{l|l|l}
935   \caption{Attribute form encodings} \label{tab:attributeformencodings} \\
936   \hline \\ \bfseries Form name&\bfseries Value &\bfseries Classes \\ \hline
937 \endfirsthead
938   \bfseries Form name&\bfseries Value &\bfseries Classes\\ \hline
939 \endhead
940   \hline \emph{Continued on next page}
941 \endfoot
942   \hline
943 \endlastfoot
944 DW\-\_FORM\-\_addr&0x01&address  \\
945 DW\-\_FORM\-\_block2&0x03&block \\
946 DW\-\_FORM\-\_block4&0x04&block  \\
947 DW\-\_FORM\-\_data2&0x05&constant \\
948 DW\-\_FORM\-\_data4&0x06&constant \\
949 DW\-\_FORM\-\_data8&0x07&constant \\
950 DW\-\_FORM\-\_string&0x08&string \\
951 DW\-\_FORM\-\_block&0x09&block \\
952 DW\-\_FORM\-\_block1&0x0a&block \\
953 DW\-\_FORM\-\_data1&0x0b&constant \\
954 DW\-\_FORM\-\_flag&0x0c&flag \\
955 DW\-\_FORM\-\_sdata&0x0d&constant    \\
956 DW\-\_FORM\-\_strp&0x0e&string         \\
957 DW\-\_FORM\-\_udata&0x0f&constant         \\
958 DW\-\_FORM\-\_ref\-\_addr&0x10&reference         \\
959 DW\-\_FORM\-\_ref1&0x11&reference          \\
960 DW\-\_FORM\-\_ref2&0x12&reference         \\
961 DW\-\_FORM\-\_ref4&0x13&reference         \\
962 DW\-\_FORM\-\_ref8&0x14&reference \\
963 DW\-\_FORM\-\_ref\-\_udata&0x15&reference  \\
964 DW\-\_FORM\-\_indirect&0x16&(see Section \refersec{datarep:abbreviationstables}) \\
965 DW\-\_FORM\-\_sec\-\_offset \ddag &0x17&\livelink{chap:lineptr}{lineptr}, \livelink{chap:loclistptr}{loclistptr}, \livelink{chap:macptr}{macptr}, \livelink{chap:rangelistptr}{rangelistptr} \\
966 DW\-\_FORM\-\_exprloc \ddag &0x18&\livelink{chap:exprloc}{exprloc} \\
967 DW\-\_FORM\-\_flag\-\_present \ddag &0x19&flag \\
968 DW\-\_FORM\-\_ref\-\_sig8 \ddag &0x20&reference \\
969  
970 \end{longtable}
971 \ddag  FORM new in DWARF Version 4 
972 \end{centering}
973
974 \section{Variable Length Data}
975 \label{datarep:variablelengthdata}
976 Integers may be encoded using ``Little Endian Base 128''
977 (LEB128) numbers. LEB128 is a scheme for encoding integers
978 densely that exploits the assumption that most integers are
979 small in magnitude.
980
981 This encoding is equally suitable whether the target machine
982 architecture represents data in big\dash\  endian or little\dash endian
983 order. It is ``little\dash endian'' only in the sense that it
984 avoids using space to represent the ``big'' end of an
985 unsigned integer, when the big end is all zeroes or sign
986 extension bits.
987
988 Unsigned LEB128 (ULEB128) numbers are encoded as follows:
989 start at the low order end of an unsigned integer and chop
990 it into 7\dash bit chunks. Place each chunk into the low order 7
991 bits of a byte. Typically, several of the high order bytes
992 will be zero; discard them. Emit the remaining bytes in a
993 stream, starting with the low order byte; set the high order
994 bit on each byte except the last emitted byte. The high bit
995 of zero on the last byte indicates to the decoder that it
996 has encountered the last byte.
997
998 The integer zero is a special case, consisting of a single
999 zero byte.
1000
1001 Table \refersec{tab:examplesofunsignedleb128encodings}
1002 gives some examples of unsigned LEB128 numbers. The
1003 0x80 in each case is the high order bit of the byte, indicating
1004 that an additional byte follows.
1005
1006
1007 The encoding for signed, two’s complement LEB128 (SLEB128)
1008 numbers is similar, except that the criterion for discarding
1009 high order bytes is not whether they are zero, but whether
1010 they consist entirely of sign extension bits. Consider the
1011 32\dash bit integer -2. The three high level bytes of the number
1012 are sign extension, thus LEB128 would represent it as a single
1013 byte containing the low order 7 bits, with the high order
1014 bit cleared to indicate the end of the byte stream. Note
1015 that there is nothing within the LEB128 representation that
1016 indicates whether an encoded number is signed or unsigned. The
1017 decoder must know what type of number to expect. 
1018 Table \refersec{tab:examplesofunsignedleb128encodings}
1019 gives some examples of unsigned LEB128 numbers and 
1020 Table \refersec{tab:examplesofsignedleb128encodings}
1021 gives some examples of signed LEB128 numbers.
1022
1023 Appendix \refersec{app:variablelengthdataencodingdecodinginformative} 
1024 gives algorithms for encoding and decoding these forms.
1025
1026
1027 \begin{centering}
1028 \setlength{\extrarowheight}{0.1cm}
1029 \begin{longtable}{l|l|l}
1030   \caption{Examples of unsigned LEB32 encodings} \label{tab:examplesofunsignedleb128encodings} \\
1031   \hline \\ \bfseries Number&\bfseries First byte &\bfseries Second byte \\ \hline
1032 \endfirsthead
1033   \bfseries Number&\bfseries First Byte &\bfseries Second byte\\ \hline
1034 \endhead
1035   \hline \emph{Continued on next page}
1036 \endfoot
1037   \hline
1038 \endlastfoot
1039 2&2& --- \\
1040 127&127& ---\\
1041 128& 0 + 0x80 & 1 \\
1042 129& 1 + 0x80 & 1 \\
1043 130& 2 + 0x80 & 1 \\
1044 12857& 57 + 0x80 & 100 \\
1045
1046 \end{longtable}
1047 \end{centering}
1048
1049
1050
1051 \begin{centering}
1052 \setlength{\extrarowheight}{0.1cm}
1053 \begin{longtable}{l|l|l}
1054   \caption{Examples of signed LEB32 encodings} \label{tab:examplesofsignedleb128encodings} \\
1055   \hline \\ \bfseries Number&\bfseries First byte &\bfseries Second byte \\ \hline
1056 \endfirsthead
1057   \bfseries Number&\bfseries First Byte &\bfseries Second byte\\ \hline
1058 \endhead
1059   \hline \emph{Continued on next page}
1060 \endfoot
1061   \hline
1062 \endlastfoot
1063 2&2& --- \\
1064 -2&0x7e& ---\\
1065 127& 127 + 0x80 & 0 \\
1066 -127& 1 + 0x80 & 0x7f \\
1067 128& 0 + 0x80 & 1 \\
1068 -128& 0 + 0x80 & 0x7f \\
1069 129& 1 + 0x80 & 1 \\
1070 -129& -x7f + 0x80 & 0xtc \\
1071
1072 \end{longtable}
1073 \end{centering}
1074
1075
1076
1077 \section{DWARF Expressions and Location Descriptions}
1078 \label{datarep:dwarfexpressionsandlocationdescriptions}
1079 \subsection{DWARF Expressions}
1080 \label{datarep:dwarfexpressions}
1081
1082 A DWARF expression is stored in a block of contiguous
1083 bytes. The bytes form a sequence of operations. Each operation
1084 is a 1\dash byte code that identifies that operation, followed by
1085 zero or more bytes of additional data. The encodings for the
1086 operations are described in 
1087 Table \refersec{tab:dwarfoperationencodings}. 
1088
1089 \begin{centering}
1090 \setlength{\extrarowheight}{0.1cm}
1091 \begin{longtable}{l|l|l|l}
1092   \caption{DWARF operation encodings} \label{tab:dwarfoperationencodings} \\
1093   \hline \\ & &\bfseries No. of  &\\ 
1094   \bfseries Operation&\bfseries Code &\bfseries Operands &\bfseries Notes\\ \hline
1095 \endfirsthead
1096    & &\bfseries No. of &\\ 
1097   \bfseries Operation&\bfseries Code &\bfseries  Operands &\bfseries Notes\\ \hline
1098 \endhead
1099   \hline \emph{Continued on next page}
1100 \endfoot
1101   \hline
1102 \endlastfoot
1103
1104 DW\-\_OP\-\_addr&0x03&1 & constant address  \\ 
1105 & & &(size target specific) \\
1106
1107 DW\-\_OP\-\_deref&0x06&0 & \\
1108
1109
1110 DW\-\_OP\-\_const1u&0x08&1&1\dash byte constant  \\
1111 DW\-\_OP\-\_const1s&0x09&1&1\dash byte constant   \\
1112 DW\-\_OP\-\_const2u&0x0a&1&2\dash byte constant   \\
1113 DW\-\_OP\-\_const2s&0x0b&1&2\dash byte constant   \\
1114 DW\-\_OP\-\_const4u&0x0c&1&4\dash byte constant    \\
1115 DW\-\_OP\-\_const4s&0x0d&1&4\dash byte constant   \\
1116 DW\-\_OP\-\_const8u&0x0e&1&8\dash byte constant   \\
1117 DW\-\_OP\-\_const8s&0x0f&1&8\dash byte constant   \\
1118 DW\-\_OP\-\_constu&0x10&1&ULEB128 constant   \\
1119 DW\-\_OP\-\_consts&0x11&1&SLEB128 constant   \\
1120 DW\-\_OP\-\_dup&0x12&0 &   \\
1121 DW\-\_OP\-\_drop&0x13&0  &   \\
1122 DW\-\_OP\-\_over&0x14&0 &   \\
1123 DW\-\_OP\-\_pick&0x15&1&1\dash byte stack index   \\
1124 DW\-\_OP\-\_swap&0x16&0 &   \\
1125 DW\-\_OP\-\_rot&0x17&0 &   \\
1126 DW\-\_OP\-\_xderef&0x18&0 &   \\
1127 DW\-\_OP\-\_abs&0x19&0 &   \\
1128 DW\-\_OP\-\_and&0x1a&0 &   \\
1129 DW\-\_OP\-\_div&0x1b&0 &   \\
1130
1131
1132
1133 DW\-\_OP\-\_minus&0x1c&0 & \\
1134 DW\-\_OP\-\_mod&0x1d&0 & \\
1135 DW\-\_OP\-\_mul&0x1e&0 & \\
1136 DW\-\_OP\-\_neg&0x1f&0 & \\
1137 DW\-\_OP\-\_not&0x20&0 & \\
1138 DW\-\_OP\-\_or&0x21&0 & \\
1139 DW\-\_OP\-\_plus&0x22&0 & \\
1140 DW\-\_OP\-\_plus\-\_uconst&0x23&1&ULEB128 addend \\
1141 DW\-\_OP\-\_shl&0x24&0 & \\
1142 DW\-\_OP\-\_shr&0x25&0 & \\
1143 DW\-\_OP\-\_shra&0x26&0 & \\
1144 DW\-\_OP\-\_xor&0x27&0 & \\
1145 DW\-\_OP\-\_skip&0x2f&1&signed 2\dash byte constant \\
1146 DW\-\_OP\-\_bra&0x28&1 & signed 2\dash byte constant \\
1147 DW\-\_OP\-\_eq&0x29&0 & \\
1148 DW\-\_OP\-\_ge&0x2a&0 & \\
1149 DW\-\_OP\-\_gt&0x2b&0 & \\
1150 DW\-\_OP\-\_le&0x2c&0 & \\
1151 DW\-\_OP\-\_lt&0x2d&0  & \\
1152 DW\-\_OP\-\_ne&0x2e&0 & \\ \hline
1153
1154
1155
1156 DW\-\_OP\-\_lit0&0x30 & 0 & \\
1157
1158 DW\-\_OP\-\_lit1&0x31 & 0& literals 0 .. 31 = \\
1159 \ldots & & & (DW\-\_OP\-\_lit0 + literal) \\
1160 DW\-\_OP\-\_lit31&0x4f & 0 & \\ \hline
1161
1162 DW\-\_OP\-\_reg0 & 0x50 & 0 & \\
1163 DW\-\_OP\-\_reg1 & 0x51 & 0&reg 0 .. 31 = \\
1164 \ldots & & & (DW\-\_OP\-\_reg0 + regnum) \\
1165 DW\-\_OP\-\_reg31 & 0x6f & 0 & \\ \hline
1166
1167 DW\-\_OP\-\_breg0 & 0x70 &1 & SLEB128 offset \\
1168 DW\-\_OP\-\_breg1 & 0x71 & 1 &base register 0 .. 31 = \\
1169 ... & &              &(DW\-\_OP\-\_breg0 + regnum) \\
1170 DW\-\_OP\-\_breg31 & 0x8f & 1 & \\ \hline
1171
1172 DW\-\_OP\-\_regx & 0x90 &1&ULEB128 register \\
1173 DW\-\_OP\-\_fbreg & 0x91&1&SLEB128 offset \\
1174 DW\-\_OP\-\_bregx & 0x92&2 &ULEB128 register followed \\
1175 & & & by SLEB128 offset \\
1176 DW\-\_OP\-\_piece & 0x93 &1& ULEB128 size of piece addressed \\
1177 DW\-\_OP\-\_deref\-\_size & 0x94 &1& 1-byte size of data retrieved \\
1178 DW\-\_OP\-\_xderef\-\_size & 0x95&1&1-byte size of data retrieved \\
1179 DW\-\_OP\-\_nop & 0x96 &0& \\
1180
1181
1182 DW\-\_OP\-\_push\-\_object\-\_address&0x97&0 &  \\
1183 DW\-\_OP\-\_call2&0x98&1& 2\dash byte offset of DIE \\
1184 DW\-\_OP\-\_call4&0x99&1& 4\dash byte offset of DIE \\
1185 DW\-\_OP\-\_call\-\_ref&0x9a&1& 4\dash\  or 8\dash byte\\
1186      &&& offset of DIE \\
1187 DW\-\_OP\-\_form\-\_tls\-\_address&0x9b &0& \\
1188 DW\-\_OP\-\_call\-\_frame\-\_cfa &0x9c &0& \\
1189 DW\-\_OP\-\_bit\-\_piece&0x9d &2&ULEB128 size followed by \\
1190 &&&ULEB128 offset\\
1191 DW\-\_OP\-\_implicit\-\_value&0x9e &2&ULEB128 size followed by \\
1192 &&&block of that size\\
1193 DW\-\_OP\-\_stack\-\_value\-\_cfa &0x9f &0& \\
1194 DW\-\_OP\-\_lo\-\_user\-\_cfa &0xe0 && \\
1195 DW\-\_OP\-\_hi\-\_user\-\_cfa &0xff && \\
1196
1197 \end{longtable}
1198 \end{centering}
1199
1200
1201 \subsection{Location Descriptions}
1202 \label{datarep:locationdescriptions}
1203
1204 A location description is used to compute the 
1205 location of a variable or other entity.
1206
1207 \subsection{Location Lists}
1208 \label{datarep:locationlists}
1209
1210 Each entry in a location list is either a location list entry,
1211 a base address selection entry, or an end of list entry.
1212
1213 A location list entry consists of two address offsets followed
1214 by a 2\dash byte length, followed by a block of contiguous bytes
1215 that contains a DWARF location description. The length
1216 specifies the number of bytes in that block. The two offsets
1217 are the same size as an address on the target machine.
1218
1219 A base address selection entry and an end of list entry each
1220 consist of two (constant or relocated) address offsets. The two
1221 offsets are the same size as an address on the target machine.
1222
1223 For a location list to be specified, the base address of
1224 the corresponding compilation unit must be defined 
1225 (see Section  \refersec{chap:normalandpartialcompilationunitentries}).
1226
1227 \section{Base Type Attribute Encodings}
1228 \label{datarep:basetypeattributeencodings}
1229
1230 The encodings of the constants used in the DW\-\_AT\-\_encoding
1231 attribute are given in 
1232 Table \refersec{tab:basetypeencodingvalues}
1233
1234 \begin{centering}
1235 \setlength{\extrarowheight}{0.1cm}
1236 \begin{longtable}{l|c}
1237   \caption{Base type encoding values} \label{tab:basetypeencodingvalues} \\
1238   \hline \\ \bfseries Base type encoding code name&\bfseries Value \\ \hline
1239 \endfirsthead
1240   \bfseries Base type encoding code name&\bfseries Value\\ \hline
1241 \endhead
1242   \hline \emph{Continued on next page}
1243 \endfoot
1244   \hline
1245 \endlastfoot
1246
1247 DW\-\_ATE\-\_address&0x01 \\
1248 DW\-\_ATE\-\_boolean&0x02 \\
1249 DW\-\_ATE\-\_complex\-\_float&0x03 \\
1250 DW\-\_ATE\-\_float&0x04 \\
1251 DW\-\_ATE\-\_signed&0x05 \\
1252 DW\-\_ATE\-\_signed\-\_char&0x06 \\
1253 DW\-\_ATE\-\_unsigned&0x07 \\
1254 DW\-\_ATE\-\_unsigned\-\_char&0x08 \\
1255 DW\-\_ATE\-\_imaginary\-\_float&0x09 \\
1256 DW\-\_ATE\-\_packed\-\_decimal&0x0a \\
1257 DW\-\_ATE\-\_numeric\-\_string&0x0b \\
1258 DW\-\_ATE\-\_edited&0x0c \\
1259 DW\-\_ATE\-\_signed\-\_fixed&0x0d \\
1260 DW\-\_ATE\-\_unsigned\-\_fixed&0x0e \\
1261 DW\-\_ATE\-\_decimal\-\_float & 0x0f \\
1262 DW\-\_ATE\-\_UTF \ddag & 0x10 \\
1263 DW\-\_ATE\-\_lo\-\_user & 0x80 \\
1264 DW\-\_ATE\-\_hi\-\_user & 0xff \\
1265
1266 \end{longtable}
1267 \ddag  Base type encoding new in DWARF Version 4
1268 \end{centering}
1269
1270
1271 The encodings of the constants used in the 
1272 DW\-\_AT\-\_decimal\-\_sign attribute 
1273 are given in 
1274 Table \refersec{tab:decimalsignencodings}.
1275
1276
1277 \begin{centering}
1278 \setlength{\extrarowheight}{0.1cm}
1279 \begin{longtable}{l|c}
1280   \caption{Decimal sign encodings} \label{tab:decimalsignencodings} \\
1281   \hline \\ \bfseries Decimal sign code name&\bfseries Value \\ \hline
1282 \endfirsthead
1283   \bfseries Decimal sign code name&\bfseries Value\\ \hline
1284 \endhead
1285   \hline \emph{Continued on next page}
1286 \endfoot
1287   \hline
1288 \endlastfoot
1289
1290 DW\-\_DS\-\_unsigned & 0x01  \\
1291 DW\-\_DS\-\_leading\-\_overpunch & 0x02  \\
1292 DW\-\_DS\-\_trailing\-\_overpunch & 0x03  \\
1293 DW\-\_DS\-\_leading\-\_separate & 0x04  \\
1294 DW\-\_DS\-\_trailing\-\_separate & 0x05  \\
1295
1296 \end{longtable}
1297 \end{centering}
1298
1299 The encodings of the constants used in the 
1300 DW\-\_AT\-\_endianity attribute are given in 
1301 Table \refersec{tab:endianityencodings}.
1302
1303 \begin{centering}
1304 \setlength{\extrarowheight}{0.1cm}
1305 \begin{longtable}{l|c}
1306   \caption{Endianity encodings} \label{tab:endianityencodings}\\
1307   \hline \\ \bfseries Endian code name&\bfseries Value \\ \hline
1308 \endfirsthead
1309   \bfseries Endian code name&\bfseries Value\\ \hline
1310 \endhead
1311   \hline \emph{Continued on next page}
1312 \endfoot
1313   \hline
1314 \endlastfoot
1315
1316 DW\-\_END\-\_default  & 0x00 \\
1317 DW\-\_END\-\_big & 0x01 \\
1318 DW\-\_END\-\_little & 0x02 \\
1319 DW\-\_END\-\_lo\-\_user & 0x40 \\
1320 DW\-\_END\-\_hi\-\_user & 0xff \\
1321
1322 \end{longtable}
1323 \end{centering}
1324
1325 \section{Accessibility Codes}
1326 \label{datarep:accessibilitycodes}
1327 The encodings of the constants used in the DW\-\_AT\-\_accessibility
1328 attribute are given in 
1329 Table \refersec{tab:accessibilityencodings}.
1330
1331 \begin{centering}
1332 \setlength{\extrarowheight}{0.1cm}
1333 \begin{longtable}{l|c}
1334   \caption{Accessibility encodings} \label{tab:accessibilityencodings}\\
1335   \hline \\ \bfseries Accessibility code name&\bfseries Value \\ \hline
1336 \endfirsthead
1337   \bfseries Accessibility code name&\bfseries Value\\ \hline
1338 \endhead
1339   \hline \emph{Continued on next page}
1340 \endfoot
1341   \hline
1342 \endlastfoot
1343
1344 DW\-\_ACCESS\-\_public&0x01  \\
1345 DW\-\_ACCESS\-\_protected&0x02 \\
1346 DW\-\_ACCESS\-\_private&0x03 \\
1347
1348 \end{longtable}
1349 \end{centering}
1350
1351
1352 \section{Visibility Codes}
1353 \label{datarep:visibilitycodes}
1354 The encodings of the constants used in the 
1355 DW\-\_AT\-\_visibility attribute are given in 
1356 Table \refersec{tab:visibilityencodings}. 
1357
1358 \begin{centering}
1359 \setlength{\extrarowheight}{0.1cm}
1360 \begin{longtable}{l|c}
1361   \caption{Visibility encodings} \label{tab:visibilityencodings}\\
1362   \hline \\ \bfseries Visiibility code name&\bfseries Value \\ \hline
1363 \endfirsthead
1364   \bfseries Visibility code name&\bfseries Value\\ \hline
1365 \endhead
1366   \hline \emph{Continued on next page}
1367 \endfoot
1368   \hline
1369 \endlastfoot
1370
1371 DW\-\_VIS\-\_local&0x01 \\
1372 DW\-\_VIS\-\_exported&0x02 \\
1373 DW\-\_VIS\-\_qualified&0x03 \\
1374
1375 \end{longtable}
1376 \end{centering}
1377
1378 \section{Virtuality Codes}
1379 \label{datarep:vitualitycodes}
1380
1381 The encodings of the constants used in the 
1382 DW\-\_AT\-\_virtuality attribute are given in 
1383 Table \refersec{tab:virtualityencodings}.
1384
1385 \begin{centering}
1386 \setlength{\extrarowheight}{0.1cm}
1387 \begin{longtable}{l|c}
1388   \caption{Virtuality encodings} \label{tab:virtualityencodings}\\
1389   \hline \\ \bfseries Virtuality code name&\bfseries Value \\ \hline
1390 \endfirsthead
1391   \bfseries Virtuality code name&\bfseries Value\\ \hline
1392 \endhead
1393   \hline \emph{Continued on next page}
1394 \endfoot
1395   \hline
1396 \endlastfoot
1397
1398 DW\-\_VIRTUALITY\-\_none&0x00 \\
1399 DW\-\_VIRTUALITY\-\_virtual&0x01 \\
1400 DW\-\_VIRTUALITY\-\_pure\-\_virtual&0x02 \\
1401
1402
1403
1404 \end{longtable}
1405 \end{centering}
1406
1407 The value 
1408 DW\-\_VIRTUALITY\-\_none is equivalent to the absence of the 
1409 DW\-\_AT\-\_virtuality
1410 attribute.
1411
1412 \section{Source Languages}
1413 \label{datarep:sourcelanguages}
1414
1415 The encodings of the constants used in the DW\-\_AT\-\_language
1416 attribute are given in 
1417 Table \refersec{tab:languageencodings}.
1418 Names marked with
1419 % If we don't force a following space it looks odd
1420 \dag \  
1421 and their associated values are reserved, but the
1422 languages they represent are not well supported. 
1423 Table \refersec{tab:languageencodings}
1424 also shows the default lower bound, if any, assumed for
1425 an omitted DW\-\_AT\-\_lower\-\_bound attribute in the context of a
1426 \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type} debugging information entry for each
1427 defined language.
1428
1429 \begin{centering}
1430 \setlength{\extrarowheight}{0.1cm}
1431 \begin{longtable}{l|c|c}
1432   \caption{Language encodings} \label{tab:languageencodings}\\
1433   \hline \\ \bfseries Language name&\bfseries Value &\bfseries Default Lower Bound \\ \hline
1434 \endfirsthead
1435   \bfseries Language name&\bfseries Value &\bfseries Default Lower Bound\\ \hline
1436 \endhead
1437   \hline \emph{Continued on next page}
1438 \endfoot
1439   \hline
1440 \endlastfoot
1441
1442 DW\-\_LANG\-\_C89&0x0001&0       \\
1443 DW\-\_LANG\-\_C&0x0002&0       \\
1444 DW\-\_LANG\-\_Ada83 \dag &0x0003&1       \\
1445 DW\-\_LANG\-\_C\-\_plus\-\_plus &0x0004&0       \\
1446 DW\-\_LANG\-\_Cobol74 \dag &0x0005&1       \\
1447 DW\-\_LANG\-\_Cobol85 \dag &0x0006&1       \\
1448 DW\-\_LANG\-\_Fortran77&0x0007&1       \\
1449 DW\-\_LANG\-\_Fortran90&0x0008&1       \\
1450 DW\-\_LANG\-\_Pascal83&0x0009&1       \\
1451 DW\-\_LANG\-\_Modula2&0x000a&1       \\
1452 DW\-\_LANG\-\_Java&0x000b&0       \\
1453 DW\-\_LANG\-\_C99&0x000c&0       \\
1454 DW\-\_LANG\-\_Ada95 \dag &0x000d&1       \\
1455 DW\-\_LANG\-\_Fortran95 &0x000e&1       \\
1456 DW\-\_LANG\-\_PLI \dag &0x000f&1 \\
1457 DW\-\_LANG\-\_ObjC&0x0010&0 \\
1458 DW\-\_LANG\-\_ObjC\-\_plus\-\_plus&0x0011&0 \\
1459 DW\-\_LANG\-\_UPC&0x0012&0 \\
1460 DW\-\_LANG\-\_D&0x0013&0 \\
1461 DW\-\_LANG\-\_Python \dag &0x0014&0 \\
1462 DW\-\_LANG\-\_lo\-\_user&0x8000 & \\
1463 DW\-\_LANG\-\_hi\-\_user&0xffff & \\
1464
1465 \end{longtable}
1466 \dag See text
1467 \end{centering}
1468
1469 \section{Address Class Encodings}
1470 \label{datarep:addressclassencodings}
1471
1472 The value of the common address class encoding 
1473 DW\-\_ADDR\-\_none is 0.
1474
1475
1476 \section{Identifier Case}
1477 \label{datarep:identifiercase}
1478
1479 The encodings of the constants used in the 
1480 DW\-\_AT\-\_identifier\-\_case attribute are given in 
1481 Table \refersec{tab:identifiercaseencodings}.
1482
1483 \begin{centering}
1484 \setlength{\extrarowheight}{0.1cm}
1485 \begin{longtable}{l|c}
1486   \caption{Identifier case encodings} \label{tab:identifiercaseencodings}\\
1487   \hline \\ \bfseries Identifier case name&\bfseries Value \\ \hline
1488 \endfirsthead
1489   \bfseries Identifier case name&\bfseries Value\\ \hline
1490 \endhead
1491   \hline \emph{Continued on next page}
1492 \endfoot
1493   \hline
1494 \endlastfoot
1495 DW\-\_ID\-\_case\-\_sensitive&0x00     \\
1496 DW\-\_ID\-\_up\-\_case&0x01     \\
1497 DW\-\_ID\-\_down\-\_case&0x02     \\
1498 DW\-\_ID\-\_case\-\_insensitive&0x03     \\
1499 \end{longtable}
1500 \end{centering}
1501
1502 \section{Calling Convention Encodings}
1503 \label{datarep:callingconventionencodings}
1504 The encodings of the constants used in the 
1505 DW\-\_AT\-\_calling\-\_convention attribute are given in
1506 Table \refersec{tab:callingconventionencodings}.
1507
1508 \begin{centering}
1509 \setlength{\extrarowheight}{0.1cm}
1510 \begin{longtable}{l|c}
1511   \caption{Calling convention encodings} \label{tab:callingconventionencodings}\\
1512   \hline \\ \bfseries Calling Convention name&\bfseries Value \\ \hline
1513 \endfirsthead
1514   \bfseries Calling Convention name&\bfseries Value\\ \hline
1515 \endhead
1516   \hline \emph{Continued on next page}
1517 \endfoot
1518   \hline
1519 \endlastfoot
1520
1521 DW\-\_CC\-\_normal&0x01     \\
1522 DW\-\_CC\-\_program&0x02     \\
1523 DW\-\_CC\-\_nocall&0x03     \\
1524 DW\-\_CC\-\_lo\-\_user&0x40     \\
1525 DW\-\_CC\-\_hi\-\_user&0xff     \\
1526
1527 \end{longtable}
1528 \end{centering}
1529
1530 \section{Inline Codes}
1531 \label{datarep:inlinecodes}
1532
1533 The encodings of the constants used in the 
1534 DW\-\_AT\-\_inline attribute are given in 
1535 Table \refersec{tab:inlineencodings}.
1536
1537 \begin{centering}
1538 \setlength{\extrarowheight}{0.1cm}
1539 \begin{longtable}{l|c}
1540   \caption{Inline encodings} \label{tab:inlineencodings}\\
1541   \hline \\ \bfseries Iline Code name&\bfseries Value \\ \hline
1542 \endfirsthead
1543   \bfseries Iline Code name&\bfseries Value\\ \hline
1544 \endhead
1545   \hline \emph{Continued on next page}
1546 \endfoot
1547   \hline
1548 \endlastfoot
1549
1550 DW\-\_INL\-\_not\-\_inlined&0x00      \\
1551 DW\-\_INL\-\_inlined&0x01      \\
1552 DW\-\_INL\-\_declared\-\_not\-\_inlined&0x02      \\
1553 DW\-\_INL\-\_declared\-\_inlined&0x03      \\
1554
1555 \end{longtable}
1556 \end{centering}
1557
1558 % this clearpage is ugly, but the following table came
1559 % out oddly without it.
1560 \clearpage
1561 \section{Array Ordering}
1562 \label{datarep:arrayordering}
1563
1564 The encodings of the constants used in the 
1565 DW\-\_AT\-\_ordering attribute are given in 
1566 Table \refersec{tab:orderingencodings}.
1567
1568 \begin{centering}
1569 \setlength{\extrarowheight}{0.1cm}
1570 \begin{longtable}{l|c}
1571   \caption{Ordering encodings} \label{tab:orderingencodings}\\
1572   \hline \\ \bfseries Ordering name&\bfseries Value \\ \hline
1573 \endfirsthead
1574   \bfseries Ordering name&\bfseries Value\\ \hline
1575 \endhead
1576   \hline \emph{Continued on next page}
1577 \endfoot
1578   \hline
1579 \endlastfoot
1580
1581 DW\-\_ORD\-\_row\-\_major&0x00  \\
1582 DW\-\_ORD\-\_col\-\_major&0x01  \\
1583
1584 \end{longtable}
1585 \end{centering}
1586
1587
1588 \section{Discriminant Lists}
1589 \label{datarep:discriminantlists}
1590
1591 The descriptors used in the 
1592 DW\-\_AT\-\_discr\-\_list attribute are 
1593 encoded as 1\dash byte constants. The
1594 defined values are given in 
1595 Table \refersec{tab:discriminantdescriptorencodings}.
1596
1597 % Odd that the 'Name' field captalized here, it is not caps elsewhere.
1598 \begin{centering}
1599 \setlength{\extrarowheight}{0.1cm}
1600 \begin{longtable}{l|c}
1601   \caption{Discriminant descriptor encodings} \label{tab:discriminantdescriptorencodings}\\
1602   \hline \\ \bfseries Descriptor Name&\bfseries Value \\ \hline
1603 \endfirsthead
1604   \bfseries Descriptor Name&\bfseries Value\\ \hline
1605 \endhead
1606   \hline \emph{Continued on next page}
1607 \endfoot
1608   \hline
1609 \endlastfoot
1610
1611 DW\-\_DSC\-\_label&0x00 \\
1612 DW\-\_DSC\-\_range&0x01 \\
1613
1614 \end{longtable}
1615 \end{centering}
1616
1617 \section{Name Lookup Tables}
1618 \label{datarep:namelookuptables}
1619
1620 Each set of entries in the table of global names contained
1621 in the .debug\_pubnames and .debug\_pubtypes sections begins
1622 with a header consisting of:
1623
1624
1625 \begin{enumerate}[1.]
1626 \item unit\_length (initial length) \\
1627 A 4\dash byte or 12\dash byte unsigned integer representing the length
1628 of the .debug\_info contribution for that compilation unit,
1629 not including the length field itself. In the 32\dash bit DWARF
1630 format, this is a 4\dash byte unsigned integer (which must be less
1631 than 0xfffffff0); in the 64\dash bit DWARF format, this consists
1632 of the 4\dash byte value 0xffffffff followed by an 8\dash byte unsigned
1633 integer that gives the actual length
1634 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1635
1636 \item  version (uhalf)
1637 A 2\dash byte unsigned integer representing the version of the
1638 DWARF information for the compilation unit
1639 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
1640 The value in this field is 4.
1641
1642 % Some say unsigned offset this just says offset: FIXME
1643 \item debug\_info\_offset (section offset) \\
1644 A 4\dash byte or 8\dash byte offset into the .debug\_info
1645 section of the compilation unit header.
1646 In
1647 the 32\dash bit DWARF format, this is a 4\dash byte unsigned offset;
1648 in the 64\dash bit DWARF format, this is an 8\dash byte unsigned offsets
1649 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1650
1651 \item  debug\_info\_length (section length) \\
1652 A 4\dash byte or 8\dash byte length containing the size in bytes of the
1653 contents of the .debug\_info section generated to represent
1654 this compilation unit. In the 32\dash bit DWARF format, this is
1655 a 4\dash byte unsigned length; in the 64\dash bit DWARF format, this
1656 is an 8-byte unsigned length 
1657 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1658
1659
1660 \end{enumerate}
1661
1662 This header is followed by a series of tuples. Each tuple
1663 consists of a 4\dash byte or 8\dash byte offset followed by a string
1664 of non\dash null bytes terminated by one null byte. 
1665 In the 32\dash bit
1666 DWARF format, this is a 4\dash byte offset; in the 64\dash bit DWARF
1667 format, it is an 8\dash byte offset. 
1668 Each set is terminated by an
1669 offset containing the value 0.
1670
1671
1672 \section{Address Range Table}
1673 \label{datarep:addrssrangetable}
1674
1675 Each set of entries in the table of address ranges contained
1676 in the .debug\_aranges section begins with a header containing:
1677
1678 \begin{enumerate}[1.]
1679 % FIXME The unit length text is not fully consistent across
1680 % these tables.
1681
1682 \item unit\_length (initial length) \\
1683 A 4-byte or 12-byte length containing the length of the
1684 set of entries for this compilation unit, not including the
1685 length field itself. In the 32-bit DWARF format, this is a
1686 4-byte unsigned integer (which must be less than 0xfffffff0);
1687 in the 64-bit DWARF format, this consists of the 4-byte value
1688 0xffffffff followed by an 8-byte unsigned integer that gives
1689 the actual length 
1690 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1691
1692 \item version (uhalf) \\
1693 A 2\dash byte version identifier containing the value 2 
1694 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
1695
1696 \item debug\_info\_offset (section offset) \\
1697 A 4\dash byte or 8\dash byte offset into the .debug\_info section of
1698 the compilation unit header. In the 32\dash bit DWARF format,
1699 this is a 4\dash byte unsigned offset; in the 64\dash bit DWARF format,
1700 this is an 8\dash byte unsigned offset 
1701 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
1702
1703 \item address\_size (ubyte) \\
1704 A 1\dash byte unsigned integer containing the size in bytes of an
1705 address (or the offset portion of an address for segmented
1706 addressing) on the target system.
1707
1708 \item segment\_size (ubyte) \\
1709 A 1\dash byte unsigned integer containing the size in bytes of a
1710 segment selector on the target system.
1711
1712 \end{enumerate}
1713
1714 This header is followed by a series of tuples. Each tuple
1715 consists of a segment, an address and a length. 
1716 The segment
1717 size is given by the segment\_size field of the header; the
1718 address and length size are each given by the address\_size
1719 field of the header. 
1720 The first tuple following the header in
1721 each set begins at an offset that is a multiple of the size
1722 of a single tuple (that is, the size of a segment selector
1723 plus twice the size of an address). 
1724 The header is padded, if
1725 necessary, to that boundary. Each set of tuples is terminated
1726 by a 0 for the segment, a 0 for the address and 0 for the
1727 length. If the segment\_size field in the header is zero,
1728 the segment selectors are omitted from all tuples, including
1729 the terminating tuple.
1730
1731
1732 \section{Line Number Information}
1733 \label{datarep:linenumberinformation}
1734
1735 The version number in the line number program header is 4
1736 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
1737
1738 The boolean values ``true'' and ``false'' 
1739 used by the line number information program are encoded
1740 as a single byte containing the value 0 
1741 for ``false,'' and a non-zero value for ``true.''
1742
1743 The encodings for the standard opcodes are given in 
1744 Table \refersec{tab:linenumberstandardopcodeencodings}.
1745
1746 % Odd that the 'Name' field captalized here, it is not caps elsewhere.
1747 \begin{centering}
1748 \setlength{\extrarowheight}{0.1cm}
1749 \begin{longtable}{l|c}
1750   \caption{Line Number Standard Opcode encodings} \label{tab:linenumberstandardopcodeencodings}\\
1751   \hline \\ \bfseries Opcode Name&\bfseries Value \\ \hline
1752 \endfirsthead
1753   \bfseries Opcode Name&\bfseries Value\\ \hline
1754 \endhead
1755   \hline \emph{Continued on next page}
1756 \endfoot
1757   \hline
1758 \endlastfoot
1759
1760 DW\-\_LNS\-\_copy&0x01 \\
1761 DW\-\_LNS\-\_advance\-\_pc&0x02 \\
1762 DW\-\_LNS\-\_advance\-\_line&0x03 \\
1763 DW\-\_LNS\-\_set\-\_file&0x04 \\
1764 DW\-\_LNS\-\_set\-\_column&0x05 \\
1765 DW\-\_LNS\-\_negate\-\_stmt&0x06 \\
1766 DW\-\_LNS\-\_set\-\_basic\-\_block&0x07 \\
1767 DW\-\_LNS\-\_const\-\_add\-\_pc*0x08 \\
1768 DW\-\_LNS\-\_fixed\-\_advance\-\_pc&0x09 \\
1769 DW\-\_LNS\-\_set\-\_prologue\-\_end&0x0a \\
1770 DW\-\_LNS\-\_set\-\_epilogue\-\_begin&0x0b \\
1771 DW\-\_LNS\-\_set\-\_isa&0x0c \\
1772
1773 \end{longtable}
1774 \end{centering}
1775
1776
1777 The encodings for the extended opcodes are given in 
1778 Table \refersec{tab:linenumberextendedopcodeencodings}.
1779
1780 \begin{centering}
1781 \setlength{\extrarowheight}{0.1cm}
1782 \begin{longtable}{l|c}
1783   \caption{Line Number Extended Opcode encodings} \label{tab:linenumberextendedopcodeencodings}\\
1784   \hline \\ \bfseries Opcode Name&\bfseries Value \\ \hline
1785 \endfirsthead
1786   \bfseries Opcode Name&\bfseries Value\\ \hline
1787 \endhead
1788   \hline \emph{Continued on next page}
1789 \endfoot
1790   \hline
1791 \endlastfoot
1792
1793 DW\-\_LNE\-\_end\-\_sequence&0x01    \\
1794 DW\-\_LNE\-\_set\-\_address&0x02\\
1795 DW\-\_LNE\-\_define\-\_file&0x03\\
1796 DW\-\_LNE\-\_set\-\_discriminator \ddag &0x04   \\
1797 DW\-\_LNE\-\_lo\-\_user&0x80   \\
1798 DW\-\_LNE\-\_hi\-\_user&0xff   \\
1799
1800 \end{longtable}
1801 \ddag Extended opcode new in DWARF Version 4.
1802 \end{centering}
1803
1804 \section{Macro Information}
1805 \label{datarep:macroinformation}
1806
1807 The source line numbers and source file indices encoded in the
1808 macro information section are represented as unsigned LEB128
1809 numbers as are the constants in a DW\-\_MACINFO\-\_vendor\-\_ext entry.
1810
1811 The macinfo type is encoded as a single byte. 
1812 The encodings are given in 
1813 Table \refersec{tab:macinfotypeencodings}.
1814
1815
1816 \begin{centering}
1817 \setlength{\extrarowheight}{0.1cm}
1818 \begin{longtable}{l|c}
1819   \caption{Macinfo Type Encodings} \label{tab:macinfotypeencodings}\\
1820   \hline \\ \bfseries Macinfo Type Name&\bfseries Value \\ \hline
1821 \endfirsthead
1822   \bfseries Macinfo Type Name&\bfseries Value\\ \hline
1823 \endhead
1824   \hline \emph{Continued on next page}
1825 \endfoot
1826   \hline
1827 \endlastfoot
1828
1829 DW\-\_MACINFO\-\_define&0x01 \\
1830 DW\-\_MACINFO\-\_undef&0x02 \\
1831 DW\-\_MACINFO\-\_start\-\_file&0x03 \\
1832 DW\-\_MACINFO\-\_end\-\_file&0x04 \\
1833 DW\-\_MACINFO\-\_vendor\-\_ext&0xff \\
1834
1835 \end{longtable}
1836 \end{centering}
1837
1838 \section{Call Frame Information}
1839 \label{datarep:callframeinformation}
1840
1841 In the 32\dash bit DWARF format, the value of the CIE id in the
1842 CIE header is 0xffffffff; in the 64\dash bit DWARF format, the
1843 value is 0xffffffffffffffff.
1844
1845 The value of the CIE version number is 4 
1846 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
1847
1848 Call frame instructions are encoded in one or more bytes. The
1849 primary opcode is encoded in the high order two bits of
1850 the first byte (that is, opcode = byte >> 6). An operand
1851 or extended opcode may be encoded in the low order 6
1852 bits. Additional operands are encoded in subsequent bytes.
1853 The instructions and their encodings are presented in
1854 Table \refersec{tab:callframeinstructionencodings}.
1855
1856 \begin{centering}
1857 \setlength{\extrarowheight}{0.1cm}
1858 \begin{longtable}{l|c|c|l|l}
1859   \caption{Call frame instruction encodings} \label{tab:callframeinstructionencodings} \\
1860   \hline \\ &\bfseries High 2 &\bfseries Low 6 &  & \\
1861   \bfseries Instruction&\bfseries Bits &\bfseries Bits &\bfseries Operand 1 &\bfseries Operand 2\\ \hline
1862 \endfirsthead
1863    & \bfseries High 2 &\bfseries Low 6 &  &\\
1864   \bfseries Instruction&\bfseries Bits &\bfseries Bits &\bfseries Operand 1 &\bfseries Operand 2\\ \hline
1865 \endhead
1866   \hline \emph{Continued on next page}
1867 \endfoot
1868   \hline
1869 \endlastfoot
1870
1871 DW\-\_CFA\-\_advance\-\_loc&0x1&delta & \\
1872 DW\-\_CFA\-\_offset&0x2&register&ULEB128 offset \\
1873 DW\-\_CFA\-\_restore&0x3&register & & \\
1874 DW\-\_CFA\-\_nop&0&0 & & \\
1875 DW\-\_CFA\-\_set\-\_loc&0&0x01&address & \\
1876 DW\-\_CFA\-\_advance\-\_loc1&0&0x02&1\dash byte delta & \\
1877 DW\-\_CFA\-\_advance\-\_loc2&0&0x03&2\dash byte delta & \\
1878 DW\-\_CFA\-\_advance\-\_loc4&0&0x04&4\dash byte delta & \\
1879 DW\-\_CFA\-\_offset\-\_extended&0&0x05&ULEB128 register&ULEB128 offset \\
1880 DW\-\_CFA\-\_restore\-\_extended&0&0x06&ULEB128 register & \\
1881 DW\-\_CFA\-\_undefined&0&0x07&ULEB128 register & \\
1882 DW\-\_CFA\-\_same\-\_value&0&0x08 &ULEB128 register & \\
1883 DW\-\_CFA\-\_register&0&0x09&ULEB128 register &ULEB128 offset \\
1884 DW\-\_CFA\-\_remember\-\_state&0&0x0a & & \\
1885 DW\-\_CFA\-\_restore\-\_state&0&0x0b & & \\
1886 DW\-\_CFA\-\_def\-\_cfa&0&0x0c &ULEB128 register&ULEB128 offset \\
1887 DW\-\_CFA\-\_def\-\_cfa\-\_register&0&0x0d&ULEB128 register & \\
1888 DW\-\_CFA\-\_def\-\_cfa\-\_offset&0&0x0e &ULEB128 offset & \\
1889 DW\-\_CFA\-\_def\-\_cfa\-\_expression&0&0x0f &BLOCK  \\
1890 DW\-\_CFA\-\_expression&0&0x10&ULEB128 register & BLOCK \\
1891
1892 DW\-\_CFA\-\_offset\-\_extended\-\_sf&0&0x11&ULEB128 register&SLEB128 offset \\
1893 DW\-\_CFA\-\_def\-\_cfa\-\_sf&0&0x12&ULEB128 register&SLEB128 offset \\
1894 DW\-\_CFA\-\_def\-\_cfa\-\_offset\-\_sf&0&0x13&SLEB128 offset & \\
1895 DW\-\_CFA\-\_val\-\_offset&0&0x14&ULEB128&ULEB128 \\
1896 DW\-\_CFA\-\_val\-\_offset\-\_sf&0&0x15&ULEB128&SLEB128 \\
1897 DW\-\_CFA\-\_val\-\_expression&0&0x16&ULEB128&BLOCK  \\
1898 DW\-\_CFA\-\_lo\-\_user&0&0x1c   & & \\
1899 DW\-\_CFA\-\_hi\-\_user&0&0x3f & & \\
1900 \end{longtable}
1901 \end{centering}
1902
1903 \section{Non-continguous Address Ranges}
1904 \label{datarep:noncontiguousaddressranges}
1905
1906 Each entry in a range list 
1907 (see Section \refersec{chap:noncontiguousaddressranges})
1908 is either a
1909 range list entry, a base address selection entry, or an end
1910 of list entry.
1911
1912 A range list entry consists of two relative addresses. The
1913 addresses are the same size as addresses on the target machine.
1914
1915 A base address selection entry and an end of list entry each
1916 consist of two (constant or relocated) addresses. The two
1917 addresses are the same size as addresses on the target machine.
1918
1919 For a range list to be specified, the base address of the
1920 corresponding compilation unit must be defined 
1921 (see Section \refersec{chap:normalandpartialcompilationunitentries}).
1922
1923
1924 \section{Dependencies and Constraints}
1925 \label{datarep:dependenciesandconstraints}
1926
1927 The debugging information in this format is intended to
1928 exist in the .debug\_abbrev, .debug\_aranges, .debug\_frame,
1929 .debug\_info, .debug\_line, .debug\_loc, .debug\_macinfo,
1930 .debug\_pubnames, .debug\_pubtypes, .debug\_ranges, .debug\_str
1931 and .debug\_types sections of an object file, or equivalent
1932 separate file or database. The information is not 
1933 word\dash aligned. Consequently: •
1934
1935 \begin{itemize}
1936 \item For the 32\dash bit DWARF format and a target architecture with
1937 32\dash bit addresses, an assembler or compiler must provide a way
1938 to produce 2\dash byte and 4\dash byte quantities without alignment
1939 restrictions, and the linker must be able to relocate a
1940 4\dash byte address or section offset that occurs at an arbitrary
1941 alignment.
1942
1943 \item For the 32\dash bit DWARF format and a target architecture with
1944 64\dash bit addresses, an assembler or compiler must provide a
1945 way to produce 2\dash byte, 4\dash byte and 8\dash byte quantities without
1946 alignment restrictions, and the linker must be able to relocate
1947 an 8\dash byte address or 4\dash byte section offset that occurs at an
1948 arbitrary alignment.
1949
1950 \item For the 64\dash bit DWARF format and a target architecture with
1951 32\dash bit addresses, an assembler or compiler must provide a
1952 way to produce 2\dash byte, 4\dash byte and 8\dash byte quantities without
1953 alignment restrictions, and the linker must be able to relocate
1954 a 4\dash byte address or 8\dash byte section offset that occurs at an
1955 arbitrary alignment.
1956
1957 \textit{It is expected that this will be required only for very large
1958 32\dash bit programs or by those architectures which support
1959 a mix of 32\dash bit and 64\dash bit code and data within the same
1960 executable object.}
1961
1962 \item For the 64\dash bit DWARF format and a target architecture with
1963 64\dash bit addresses, an assembler or compiler must provide a
1964 way to produce 2\dash byte, 4\dash byte and 8\dash byte quantities without
1965 alignment restrictions, and the linker must be able to
1966 relocate an 8\dash byte address or section offset that occurs at
1967 an arbitrary alignment.
1968 \end{itemize}
1969
1970 \section{Integer Representation Names}
1971 \label{datarep:integerrepresentationnames}
1972
1973 The sizes of the integers used in the lookup by name, lookup
1974 by address, line number and call frame information sections
1975 are given in
1976 Table 41 \refersec{tab:integerrepresentationnames}.
1977
1978 \begin{centering}
1979 \setlength{\extrarowheight}{0.1cm}
1980 \begin{longtable}{c|l}
1981   \caption{Integer Representation Names} \label{tab:integerrepresentationnames}\\
1982   \hline \\ \bfseries Representation Name&\bfseries Representation \\ \hline
1983 \endfirsthead
1984   \bfseries Representation Name&\bfseries Representation\\ \hline
1985 \endhead
1986   \hline \emph{Continued on next page}
1987 \endfoot
1988   \hline
1989 \endlastfoot
1990
1991 sbyte&  signed, 1\dash byte integer \\
1992 ubyte&unsigned, 1\dash byte integer \\
1993 uhalf&unsigned, 2\dash byte integer \\
1994 uword&unsigned, 4\dash byte integer \\
1995
1996 \end{longtable}
1997 \end{centering}
1998
1999 \section{Type Signature Computation}
2000 \label{datarep:typesignaturecomputation}
2001
2002 A type signature is computed only by the DWARF producer;
2003 it is used by a DWARF consumer to resolve type references to
2004 the type definitions that are contained in type units.
2005
2006 The type signature for a type T0 is formed from the MD5
2007 hash of a flattened description of the type. The flattened
2008 description of the type is a byte sequence derived from the
2009 DWARF encoding of the type as follows:
2010
2011 \begin{enumerate}[1.]
2012
2013 \item Start with an empty sequence S and a list V of visited
2014 types, where V is initialized to a list containing the type
2015 T0 as its single element. Elements in V are indexed from 1,
2016 so that V[1] is T0.
2017
2018 \item If the debugging information entry represents a type that
2019 is nested inside another type or a namespace, append to S
2020 the type’s context as follows: For each surrounding type
2021 or namespace, beginning with the outermost such construct,
2022 append the letter 'C', the DWARF tag of the construct, and
2023 the name (taken from the DW\-\_AT\-\_name attribute) of the type
2024 or namespace (including its trailing null byte).
2025
2026 \item  Append to S the letter 'D', followed by the DWARF tag of
2027 the debugging information entry.
2028
2029 \item For each of the following attributes that are present in
2030 the debugging information entry, in the order listed below,
2031 append to S a marker letter (see below), the DWARF attribute
2032 code, and the attribute value.
2033
2034 \begin{itemize}
2035 \item DW\-\_AT\-\_name
2036 \item DW\-\_AT\-\_accessibility
2037 \item DW\-\_AT\-\_address\-\_class
2038 \item DW\-\_AT\-\_allocated
2039 \item DW\-\_AT\-\_artificial
2040 \item DW\-\_AT\-\_associated
2041 \item DW\-\_AT\-\_binary\-\_scale
2042 \item DW\-\_AT\-\_bit\-\_offset
2043 \item DW\-\_AT\-\_bit\-\_size
2044 \item DW\-\_AT\-\_bit\-\_stride
2045 \item DW\-\_AT\-\_byte\-\_size
2046 \item DW\-\_AT\-\_byte\-\_stride
2047 \item DW\-\_AT\-\_const\-\_expr
2048 \item DW\-\_AT\-\_const\-\_value
2049 \item DW\-\_AT\-\_containing\-\_type
2050 \item DW\-\_AT\-\_count
2051 \item DW\-\_AT\-\_data\-\_bit\-\_offset
2052 \item DW\-\_AT\-\_data\-\_location
2053 \item DW\-\_AT\-\_data\-\_member\-\_location
2054 \item DW\-\_AT\-\_decimal\-\_scale
2055 \item DW\-\_AT\-\_decimal\-\_sign
2056 \item DW\-\_AT\-\_default\-\_value
2057 \item DW\-\_AT\-\_digit\-\_count
2058 \item DW\-\_AT\-\_discr
2059 \item DW\-\_AT\-\_discr\-\_list
2060 \item DW\-\_AT\-\_discr\-\_value
2061 \item DW\-\_AT\-\_encoding
2062 \item DW\-\_AT\-\_enum\-\_class
2063 \item DW\-\_AT\-\_endianity
2064 \item DW\-\_AT\-\_explicit
2065 \item DW\-\_AT\-\_is\-\_optional
2066 \item DW\-\_AT\-\_location
2067 \item DW\-\_AT\-\_lower\-\_bound
2068 \item DW\-\_AT\-\_mutable
2069 \item DW\-\_AT\-\_ordering
2070 \item DW\-\_AT\-\_picture\-\_string
2071 \item DW\-\_AT\-\_prototyped
2072 \item DW\-\_AT\-\_small
2073 \item DW\-\_AT\-\_segment
2074 \item DW\-\_AT\-\_string\-\_length
2075 \item DW\-\_AT\-\_threads\-\_scaled
2076 \item DW\-\_AT\-\_upper\-\_bound
2077 \item DW\-\_AT\-\_use\-\_location
2078 \item DW\-\_AT\-\_use\-\_UTF8
2079 \item DW\-\_AT\-\_variable\-\_parameter
2080 \item DW\-\_AT\-\_virtuality
2081 \item DW\-\_AT\-\_visibility
2082 \item DW\-\_AT\-\_vtable\-\_elem\-\_location
2083 \end{itemize}
2084
2085 Note that except for the initial DW\-\_AT\-\_name attribute,
2086 attributes are appended in order according to the alphabetical
2087 spelling of their identifier.
2088
2089 If an implementation defines any vendor-specific attributes,
2090 any such attributes that are essential to the definition of
2091 the type should also be included at the end of the above list,
2092 in their own alphabetical suborder.
2093
2094 An attribute that refers to another type entry T is processed
2095 as follows: (a) If T is in the list V at some V[x], use the
2096 letter 'R' as the marker and use the unsigned LEB128 encoding
2097 of x as the attribute value; otherwise, (b) use the letter 'T'
2098 as the marker, process the type T recursively by performing
2099 Steps 2 through 7, and use the result as the attribute value.
2100
2101 Other attribute values use the letter 'A' as the marker, and
2102 the value consists of the form code (encoded as an unsigned
2103 LEB128 value) followed by the encoding of the value according
2104 to the form code. To ensure reproducibility of the signature,
2105 the set of forms used in the signature computation is limited
2106 to the following: DW\-\_FORM\-\_sdata, 
2107 DW\-\_FORM\-\_flag, 
2108 DW\-\_FORM\-\_string,
2109 and DW\-\_FORM\-\_block.
2110
2111 \item If the tag in Step 3 is one of \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type},
2112 \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type}, 
2113 \livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type},
2114 \livelink{chap:DWTAGptrtomembertype}{DW\-\_TAG\-\_ptr\-\_to\-\_member\-\_type}, 
2115 or \livelink{chap:DWTAGfriend}{DW\-\_TAG\-\_friend}, and the referenced
2116 type (via the DW\-\_AT\-\_type or 
2117 DW\-\_AT\-\_friend attribute) has a
2118 DW\-\_AT\-\_name attribute, append to S the letter 'N', the DWARF
2119 attribute code (DW\-\_AT\-\_type or 
2120 DW\-\_AT\-\_friend), the context of
2121 the type (according to the method in Step 2), the letter 'E',
2122 and the name of the type. For \livelink{chap:DWTAGfriend}{DW\-\_TAG\-\_friend}, if the referenced
2123 entry is a \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}, the context is omitted and the
2124 name to be used is the ABI-specific name of the subprogram
2125 (e.g., the mangled linker name).
2126
2127
2128 \item 6.If the tag in Step 3 is not one of \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type},
2129 \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type}, 
2130 \livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type},
2131 \livelink{chap:DWTAGptrtomembertype}{DW\-\_TAG\-\_ptr\-\_to\-\_member\-\_type}, or 
2132 \livelink{chap:DWTAGfriend}{DW\-\_TAG\-\_friend}, but has
2133 a DW\-\_AT\-\_type attribute, or if the referenced type (via
2134 the DW\-\_AT\-\_type or 
2135 DW\-\_AT\-\_friend attribute) does not have a
2136 DW\-\_AT\-\_name attribute, the attribute is processed according to
2137 the method in Step 4 for an attribute that refers to another
2138 type entry.
2139
2140
2141 \item Visit each child C of the debugging information
2142 entry as follows: If C is a nested type entry or a member
2143 function entry, and has a DW\-\_AT\-\_name attribute, append to
2144 S the letter 'S', the tag of C, and its name; otherwise,
2145 process C recursively by performing Steps 3 through 7,
2146 appending the result to S. Following the last child (or if
2147 there are no children), append a zero byte.
2148 \end{enumerate}
2149
2150
2151
2152 For the purposes of this algorithm, if a debugging information
2153 entry S has a 
2154 DW\-\_AT\-\_specification 
2155 attribute that refers to
2156 another entry D (which has a 
2157 DW\-\_AT\-\_declaration 
2158 attribute),
2159 then S inherits the attributes and children of D, and S is
2160 processed as if those attributes and children were present in
2161 the entry S. Exception: if a particular attribute is found in
2162 both S and D, the attribute in S is used and the corresponding
2163 one in D is ignored.
2164
2165 DWARF tag and attribute codes are appended to the sequence
2166 as unsigned LEB128 values, using the values defined earlier
2167 in this chapter.
2168
2169 \textit{A grammar describing this computation may be found in
2170 Appendix \refersec{app:typesignaturecomputationgrammar}.
2171 }
2172
2173 \textit{An attribute that refers to another type entry should
2174 be recursively processed or replaced with the name of the
2175 referent (in Step 4, 5 or 6). If neither treatment applies to
2176 an attribute that references another type entry, the entry
2177 that contains that attribute should not be considered for a
2178 separate type unit.}
2179
2180 \textit{If a debugging information entry contains an attribute from
2181 the list above that would require an unsupported form, that
2182 entry should not be considered for a separate type unit.}
2183
2184 \textit{A type should be considered for a separate type unit only
2185 if all of the type entries that it contains or refers to in
2186 Steps 6 and 7 can themselves each be considered for a separate
2187 type unit.}
2188
2189 Where the DWARF producer may reasonably choose two or more
2190 different forms for a given attribute, it should choose
2191 the simplest possible form in computing the signature. (For
2192 example, a constant value should be preferred to a location
2193 expression when possible.)
2194
2195 Once the string S has been formed from the DWARF encoding,
2196 an MD5 hash is computed for the string and the lower 64 bits
2197 are taken as the type signature.
2198
2199 \textit{The string S is intended to be a flattened representation of
2200 the type that uniquely identifies that type (i.e., a different
2201 type is highly unlikely to produce the same string).}
2202
2203 \textit{A debugging information entry should not be placed in a
2204 separate type unit if any of the following apply:}
2205
2206 \begin{itemize}
2207
2208 \item \textit{The entry has an attribute whose value is a location
2209 expression, and the location expression contains a reference to
2210 another debugging information entry (e.g., a DW\-\_OP\-\_call\-\_ref
2211 operator), as it is unlikely that the entry will remain
2212 identical across compilation units.}
2213
2214 \item \textit{The entry has an attribute whose value refers
2215 to a code location or a location list.}
2216
2217 \item \textit{The entry has an attribute whose value refers
2218 to another debugging information entry that does not represent
2219 a type.}
2220 \end{itemize}
2221
2222
2223 \textit{Certain attributes are not included in the type signature:}
2224
2225 \begin{itemize}
2226 \item \textit{The DW\-\_AT\-\_declaration attribute is not included because it
2227 indicates that the debugging information entry represents an
2228 incomplete declaration, and incomplete declarations should
2229 not be placed in separate type units.}
2230
2231 \item \textit{The DW\-\_AT\-\_description attribute is not included because
2232 it does not provide any information unique to the defining
2233 declaration of the type.}
2234
2235 \item \textit{The DW\-\_AT\-\_decl\-\_file, DW\-\_AT\-\_decl\-\_line, and
2236 DW\-\_AT\-\_decl\-\_column attributes are not included because they
2237 may vary from one source file to the next, and would prevent
2238 two otherwise identical type declarations from producing the
2239 same hash.}
2240
2241 \end{itemize}