892b46a80c3e673906c3dd70d93d411332dfac78
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
1 \chapter[Compression (Informative)]{DWARF Compression and Duplicate Elimination (Informative)}
2 \label{dwarfcompressionandduplicateeliminationinformative}
3
4 % It seemed difficult to get close to the same layout and 
5 % captioning as DWARF4 here with figures as they moved (floated)
6 % making it hard to follow.  Hence this uses fewer figures.
7
8 DWARF can use a lot of disk space.
9
10 This is especially true for C++, where the depth and complexity
11 of headers can mean that many, many (possibly thousands of)
12 declarations are repeated in every compilation unit. C++
13 templates can also mean that some functions and their DWARF
14 descriptions get duplicated.
15
16 This Appendix describes techniques for using the DWARF
17 representation in combination with features and characteristics
18 of some common object file representations to reduce redundancy
19 without losing information. It is worth emphasizing that none
20 of these techniques are necessary to provide a complete and
21 accurate DWARF description; they are solely concerned with
22 reducing the size of DWARF information.
23
24 The techniques described here depend more directly and more
25 obviously on object file concepts and linker mechanisms than
26 most other parts of DWARF. While the presentation tends to
27 use the vocabulary of specific systems, this is primarily to
28 aid in describing the techniques by appealing to well\dash known
29 terminology. These techniques can be employed on any system
30 that supports certain general functional capabilities
31 (described below).
32
33
34 \section{Using Compilation Units}
35 \label{app:usingcompilationunits}
36
37 \subsection{Overview}
38 The general approach is to break up the debug information of
39 a compilation into separate normal and partial compilation
40 units, each consisting of one or more sections. By arranging
41 that a sufficiently similar partitioning occurs in other
42 compilations, a suitable system linker can delete redundant
43 groups of sections when combining object files.
44
45 \textit{The following uses some traditional section naming here
46 but aside from the DWARF sections, the names are just meant
47 to suggest traditional contents as a way of explaining the
48 approach, not to be limiting.}
49
50 A traditional relocatable object output 
51 from a single compilation might contain sections 
52 named:
53 \begin{alltt}
54     \addtoindex{.data}
55     \addtoindex{.text}
56     \addtoindex{.debug\_info}
57     \addtoindex{.debug\_abbrev}
58     \addtoindex{.debug\_line}
59     \addtoindex{.debug\_aranges}
60 \end{alltt}
61 A relocatable object from a compilation system 
62 attempting duplicate DWARF elimination might
63 contain sections as in:
64
65 \begin{alltt}
66     \addtoindex{.data}
67     \addtoindex{.text}
68     \addtoindex{.debug\_info}
69     \addtoindex{.debug\_abbrev}
70     \addtoindex{.debug\_line}
71     \addtoindex{.debug\_aranges}
72 \end{alltt}
73
74 followed (or preceded, the order is not significant) 
75 by a series of section groups:
76 \begin{alltt}
77 ==== Section group 1
78     \addtoindex{.debug\_info}
79     \addtoindex{.debug\_abbrev}
80     \addtoindex{.debug\_line}
81 ==== ...
82 ==== Section group N
83     \addtoindex{.debug\_info}
84     \addtoindex{.debug\_abbrev}
85     \addtoindex{.debug\_line}
86 \end{alltt}
87
88 where each section group might or might not contain executable
89 code (\textit{.text} sections) or data (\textit{.data} sections).
90
91 A \textit{section group} is a named set of section contributions
92 within an object file with the property that the entire set
93 of section contributions must be retained or discarded as a
94 whole; no partial elimination is allowed. Section groups can
95 generally be handled by a linker in two ways:
96
97 \begin{enumerate}[1.]
98 \item Given multiple identical (duplicate) section groups,
99 one of them is chosen to be kept and used, while the rest
100 are discarded.
101
102 \item Given a section group that is not referenced from any
103 section outside of the section group, the section group
104 is discarded.
105
106
107 \end{enumerate}
108
109
110 Which handling applies may be indicated by the section group
111 itself and/or selection of certain linker options.
112
113 For example, if a linker determines that section group 1
114 from A.o and section group 3 from B.o are identical, it could
115 discard one group and arrange that all references in A.o and
116 B.o apply to the remaining one of the two identical section
117 groups. This saves space.
118
119 An important part of making it possible to “redirect”
120 references to the surviving section group is the use of
121 consistently chosen linker global symbols for referring to
122 locations within each section group. It follows that references
123 are simply to external names and the linker already knows
124 how to match up references and definitions.
125
126 What is minimally needed from the object file format and system
127 linker (outside of DWARF itself, and normal object/linker
128 facilities such as simple relocations) are:
129
130 \begin{enumerate}[1.]
131
132 \item A means of referencing from inside one \addtoindex{.debug\_info}
133 compilation unit to another 
134 \addtoindex{.debug\_info} compilation unit
135 (\livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} provides this).
136
137 \item A means of having multiple contributions to specific sections
138 (for example, \addtoindex{.debug\_info}, and so on) in a single object file.
139
140 \item  A means of identifying a section group (giving it a name).
141
142 \item A means of identifying which sections go together to make
143 up a section group, so that the group can be treated as a unit
144 (kept or discarded).
145
146 \item  A means of indicating how each section group should be
147 processed by the linker.
148
149 \end{enumerate}
150
151 \textit{The notion of section and section contribution used here
152 corresponds closely to the similarly named concepts in the
153 ELF object file representation. The notion of section group is
154 an abstraction of common extensions of the ELF representation
155 widely known as ``COMDATs'' or ``COMDAT sections''. (Other
156 object file representations provide COMDAT\dash style mechanisms as
157 well.) There are several variations in the COMDAT schemes in
158 common use, any of which should be sufficient for the purposes
159 of the DWARF duplicate elimination techniques described here.}
160
161 \subsection{Naming and Usage Considerations}
162 \label{app:namingandusageconsiderations}
163
164 A precise description of the means of deriving names usable
165 by the linker to access DWARF entities is not part of this
166 specification. Nonetheless, an outline of a usable approach
167 is given here to make this more understandable and to guide
168 implementors.
169
170 Implementations should clearly document their naming conventions.
171
172 In the following, it will be helpful to refer to the examples
173 in 
174 Figure \refersec{app:duplicateeliminationexample1csource}
175 through 
176 Figure \refersec{app:duplicateeliminationexample2companiondwarf}
177 of 
178 Section \refersec{app:examples}.
179
180 \textbf{Section Group Names}
181
182 Section groups must have a section group name. For the subsequent C++ example, a name like
183
184 <producer-prefix>.<file-designator>.<gid-number>
185
186 will suffice, where
187
188 \begin{itemize}
189
190 \item  \textless producer\dash prefix \textgreater 
191 is some string specific to the
192 producer, which has a language\dash designation embedded in the
193 name when appropriate. (Alternatively, the language name
194 could be embedded in the 
195 \textless gid\dash number \textgreater).
196
197
198 \item  \textless file\dash designator \textgreater
199 names the file, such as wa.h in
200 the example.
201
202
203 \item  \textless gid\dash number \textgreater
204 is a string generated to identify the
205 specific wa.h header file in such a way that
206
207 \begin{itemize}
208
209 \item  a 'matching' output from another compile generates
210 the same 
211 \textless gid\dash number \textgreater,
212 and
213
214 \item  a non\dash matching output (say because of \#defines)
215 generates a different 
216 \textless gid\dash number \textgreater.
217 \end{itemize}
218
219 \end{itemize}
220
221 \textit{It may be useful to think of a 
222 \textless gid\dash number \textgreater
223 as a kind
224 of ``digital signature'' that allows a fast test for the
225 equality of two section groups.}
226
227 So, for example, the section group corresponding to file wa.h
228 above is given the name \textit{my.compiler.company.cpp.wa.h.123456}.
229
230
231
232 \textbf{Debugging Information Entry Names}
233
234 Global labels for debugging information entries (need explained
235 below) within a section group can be given names of the form
236
237 \begin{alltt}
238     <prefix>.<file-designator>.<gid-number>.<die-number>
239 \end{alltt}
240
241 such as
242
243 \begin{alltt}
244     my.compiler.company.wa.h.123456.987
245 \end{alltt}
246
247 where
248 \begin{itemize}
249 \item \textless prefix \textgreater\  
250 distinguishes this as a DWARF debug info name, and should identify the producer
251 and, when appropriate, the language.
252 \item \textless file\dash designator\textgreater\  
253 and 
254 \textless gid\dash number \textgreater
255 are as above.
256
257 \item  \textless die\dash number \textgreater
258 could be a number sequentially assigned 
259 to entities (tokens, perhaps) found
260 during compilation.
261
262 \end{itemize}
263
264 In general, every point in the section group 
265 \addtoindex{.debug\_info} that
266 could be referenced from outside by any compilation unit must
267 normally have an external name generated for it in the linker
268 symbol table, whether the current compilation references all
269 those points or not.
270
271 The completeness of the set of names generated is a
272 quality\dash of\dash implementation issue.
273
274 It is up to the producer to ensure that if 
275 <die-numbers>
276 \textless die\dash numbers \textgreater
277 in separate compilations would not match properly then a
278 distinct 
279 \textless gid\dash number \textgreater
280 is generated.
281
282 Note that only section groups that are designated as
283 duplicate\dash removal\dash applies actually require the
284 \begin{alltt}
285     <prefix>.<file-designator>.<gid-number>.<die-number>
286 \end{alltt}
287 external labels for debugging information entries as all other
288 section group sections can use 'local' labels 
289 (section\dash relative
290 relocations).
291
292 (This is a consequence of separate compilation, not a rule
293 imposed by this document.)
294
295 \textit{Local labels use references with form \livelink{chap:DWFORMref4}{DW\-\_FORM\-\_ref4}
296 or 
297 \livelink{chap:DWFORMref8}{DW\-\_FORM\-\_ref8}. 
298 (These are affected by relocations
299 so 
300 \livelink{chap:DWFORMrefudata}{DW\-\_FORM\-\_ref\-\_udata}, 
301 \livelink{chap:DWFORMref1}{DW\-\_FORM\-\_ref1} and 
302 \livelink{chap:DWFORMref2}{DW\-\_FORM\-\_ref2} are
303 normally not usable and 
304 \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} is not necessary
305 for a local label.)}
306
307 \textbf{Use of \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} versus 
308 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}}
309
310 A section group compilation unit that uses 
311 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
312 is like any other compilation unit, in that its contents
313 are evaluated by consumers as though it were an ordinary
314 compilation unit.
315
316 An \#include directive appearing outside any other
317 declarations is a good candidate to be represented using
318 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}. 
319 However, an \#include appearing inside
320 a C++ namespace declaration or a function, for example, is
321 not a good candidate because the entities included are not
322 necessarily file level entities.
323
324 This also applies to Fortran INCLUDE lines when declarations
325 are included into a procedure or module context.
326
327 Consequently a compiler must use \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} (instead
328 of \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}) in a section group whenever the section
329 group contents are not necessarily globally visible. This
330 directs consumers to ignore that compilation unit when scanning
331 top level declarations and definitions.
332
333 The \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} compilation unit will be referenced
334 from elsewhere and the referencing locations give the
335 appropriate context for interpreting the partial compilation
336 unit.
337
338 A \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} entry may have, as appropriate, any of
339 the attributes assigned to a \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}.
340
341
342 \textbf{Use of \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}}
343
344 A \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit} debugging information entry has an
345 \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute referencing a \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} or
346 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} debugging information entry.
347
348 A \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit} debugging information entry refers
349 to a 
350 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} or 
351 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} debugging
352 information entry to specify that the 
353 \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} or
354 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} contents logically appear at the point
355 of the 
356 \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit} entry.
357
358
359 \textbf{Use of \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr}}
360
361 Use 
362 \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} to reference from one compilation
363 unit's debugging information entries to those of another
364 compilation unit.
365
366 When referencing into a removable section group 
367 \addtoindex{.debug\_info}
368 from another \addtoindex{.debug\_info} (from anywhere), the
369 \begin{alltt}
370 <prefix>.<file-designator>.<gid-number>.<die-number>
371 \end{alltt}
372 name should be used for an external symbol and a relocation
373 generated based on that name.
374
375 When referencing into a non-section group 
376 \addtoindex{.debug\_info},
377 from another \addtoindex{.debug\_info} (from anywhere) 
378 \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} is
379 still the form to be used, but a section\dash relative relocation
380 generated by use of a non-exported name (often called an
381 ``internal name'') may be used for references within the
382 same object file.
383
384 \subsection{Examples}
385 \label{app:examples}
386
387 This section provides several examples in order to have a
388 concrete basis for discussion.
389
390 In these examples, the focus is on the arrangement of DWARF
391 information into sections (specifically the 
392 \addtoindex{.debug\_info}
393 section) and the naming conventions used to achieve references
394 into section groups. In practice, all of the examples that
395 follow involve DWARF sections other than just 
396 \addtoindex{.debug\_info}
397 (for example, \addtoindex{.debug\_line}, 
398 \addtoindex{.debug\_aranges}, or others);
399 however, only the \addtoindex{.debug\_info}
400 section is shown to keep the
401 examples compact and easier to read.
402
403 The grouping of sections into a named set is shown, but the means for achieving this in terms of
404 the underlying object language is not (and varies from system to system).
405
406 \subsubsection{C++ Example}
407
408 The C++ source in 
409 Section \refersec{app:duplicateeliminationexample1csource}
410 is used to illustrate the DWARF
411 representation intended to allow duplicate elimination.
412
413 \paragraph{Duplicate elimination example 1: C++ Source} 
414 \label{app:duplicateeliminationexample1csource}
415
416 File wa.h
417
418 \begin{lstlisting}
419 struct A {
420    int i;
421 };
422 \end{lstlisting}
423
424 File wa.C
425
426 \begin{lstlisting}
427 #include "wa.h";
428 int
429 f(A &a)
430 {
431     return a.i + 2;
432 }
433 \end{lstlisting}
434
435
436 section \refersec{app:duplicateeliminationexample1dwarfsectiongroup}
437 shows the section group corresponding to the included file 
438 wa.h.
439
440
441 \paragraph{Duplicate elimination example 1: DWARF section group} 
442
443 \label{app:duplicateeliminationexample1dwarfsectiongroup}
444 % FIXME: the DWFORMrefn could use rethinking
445 \begin{alltt}
446 ==== Section group name:
447     my.compiler.company.cpp.wa.h.123456
448 == section \addtoindex{.debug\_info}
449 DW.cpp.wa.h.123456.1: ! linker global symbol
450     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
451         \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language}(\livelink{chap:DWLANGCplusplus}{DW\-\_LANG\-\_C\-\_plus\-\_plus})
452         ...  ! other unit attributes
453 DW.cpp.wa.h.123456.2: ! linker global symbol
454     \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
455         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("int")
456 DW.cpp.wa.h.123456.3: ! linker global symbol
457     \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
458         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("A")
459 DW.cpp.wa.h.123456.4: ! linker global symbol
460         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
461         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("i")
462         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(\livelink{chap:DWFORMrefn}{DW\-\_FORM\-\_refn} to DW.cpp.wa.h.123456.2)
463             ! (This is a local reference, so the more
464             ! compact form \livetarg{chap:DWFORMrefn}{DW\-\_FORM\-\_refn} 
465             ! for n 1,2,4, or 8 can be used)
466 \end{alltt}
467
468
469 Figure \refersec{app:duplicateeliminationexample1primarycompilationunit}
470 shows the ``normal'' DWARF sections, which are not part of
471 any section group, and how they make use of the information
472 in the section group shown above.
473
474 \paragraph{Duplicate elimination example 1: primary compilation unit} 
475 \label{app:duplicateeliminationexample1primarycompilationunit}
476 \begin{alltt}
477 == section .text
478     [generated code for function f]
479 == section \addtoindex{.debug\_info}
480     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
481 .L1:                   ! local (non-linker) symbol
482         \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type}
483             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.cpp.wa.h.123456.3)
484         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
485             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("f")
486             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.cpp.wa.h.123456.2)
487             \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
488                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("a")
489                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to .L1)
490         ...
491 \end{alltt}
492
493 This example uses \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} for the section group,
494 implying that the contents of the compilation unit are
495 globally visible (in accordance with C++ language rules).
496 \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} is not needed for the same reason.
497
498 \subsubsection{Fortran Example}
499
500
501 For a Fortran example, consider 
502 Figure \refersec{app:duplicateeliminationexample2fortransource}.
503
504
505 \paragraph{Duplicate elimination example 2: Fortran source} 
506 \label{app:duplicateeliminationexample2fortransource}
507
508 File CommonStuff.fh
509
510 \begin{lstlisting}
511 IMPLICIT INTEGER(A-Z)
512 COMMON /Common1/ C(100)
513 PARAMETER(SEVEN = 7)
514 \end{lstlisting}
515
516 File Func.f
517 \begin{lstlisting}
518
519 FUNCTION FOO (N)
520 INCLUDE 'CommonStuff.fh'
521 FOO = C(N + SEVEN)
522 RETURN
523 END
524 \end{lstlisting}
525
526
527 Section \refersec{app:duplicateeliminationexample2dwarfsectiongroup}
528 shows the section group 
529 corresponding to the included file CommonStuff.fh.
530
531 \paragraph{Duplicate elimination example 2: DWARF section group}
532 \label{app:duplicateeliminationexample2dwarfsectiongroup}
533
534 \begin{alltt}
535 ==== Section group name:
536
537     my.f90.company.f90.CommonStuff.fh.654321
538
539 == section \addtoindex{.debug\_info}
540
541 DW.myf90.CommonStuff.fh.654321.1:    ! linker global symbol
542     \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}
543         ! ...compilation unit attributes, including...
544         \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language}(\livelink{chap:DWLANGFortran90}{DW\-\_LANG\-\_Fortran90})
545         \livelink{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case}(\livelink{chap:DWIDcaseinsensitive}{DW\-\_ID\-\_case\-\_insensitive})
546
547 DW.myf90.CommonStuff.fh.654321.2: ! linker global symbol
548 3\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
549         ! unnamed
550         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.f90.F90\$main.f.2)
551             ! base type INTEGER
552         \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
553             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.f90.F90\$main.f.2)
554                 ! base type INTEGER)
555             \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(constant 1)
556             \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(constant 100)
557
558 DW.myf90.CommonStuff.fh.654321.3: ! linker global symbol
559     \livelink{chap:DWTAGcommonblock}{DW\-\_TAG\-\_common\-\_block}
560         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Common1")
561         \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(Address of common \nolink{block} Common1)
562         \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
563             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("C")
564             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 3\$)
565             \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(address of C)
566
567 DW.myf90.CommonStuff.fh.654321.4: ! linker global symbol
568     \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant}
569         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("SEVEN")
570         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.f90.F90\$main.f.2)
571             ! base type INTEGER
572         \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}(constant 7)
573 \end{alltt}
574
575 Section \refersec{app:duplicateeliminationexample2primaryunit}
576 shows the sections for the primary compilation unit.
577
578
579
580 \paragraph{Duplicate elimination example 2: primary unit }
581 \label{app:duplicateeliminationexample2primaryunit}
582 \begin{alltt}
583 == section .text
584     [code for function Foo]
585
586 == section \addtoindex{.debug\_info}
587     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
588         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
589             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Foo")
590             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.f90.F90\$main.f.2)
591                 ! base type INTEGER
592             \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}
593                 \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to
594                     DW.myf90.CommonStuff.fh.654321.1)
595             \livelink{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion} ! For Common1
596                 \livelink{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference}(reference to
597                     DW.myf90.CommonStuff.fh.654321.3)
598             \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable} ! For function result
599                 \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Foo")
600                     \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to DW.f90.F90\$main.f.2)
601                         ! base type INTEGER
602 \end{alltt}
603
604 A companion main program is shown in 
605 Section \refersec{app:duplicateeliminationexample2companionsource}
606
607 \paragraph{Duplicate elimination example 2: companion source }
608 \label{app:duplicateeliminationexample2companionsource}
609
610 File Main.f 
611
612 \begin{lstlisting}
613 INCLUDE 'CommonStuff.fh'
614 C(50) = 8
615 PRINT *, 'Result = ', FOO(50 - SEVEN)
616 END
617 \end{lstlisting}
618
619 That main program results in an object file that
620 contained a duplicate of the section group named
621 my.f90.company.f90.CommonStuff.fh.654321 
622 corresponding to the
623 included file as well as the remainder of the main subprogram
624 as shown in 
625 Section \refersec{app:duplicateeliminationexample2companiondwarf}.
626
627 \paragraph{Duplicate elimination example 2: companion DWARF }
628 \label{app:duplicateeliminationexample2companiondwarf}
629
630 \begin{alltt}
631 == section \addtoindex{.debug\_info}
632     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
633         \livelink{chap:DWATname}{DW\-\_AT\-\_name}(F90\$main)
634         \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
635             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("INTEGER")
636             \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding}(\livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed})
637             \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}(...)
638
639         \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
640             ...
641         ...  ! other base types
642         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
643             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F90\$main")
644             \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}
645                 \livelink{chap:DWATimport}{DW\-\_AT\-\_import}(reference to
646                     DW.myf90.CommonStuff.fh.654321.1)
647             \livelink{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion} ! for Common1
648                 \livelink{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference}(reference to
649                     DW.myf90.CommonStuff.fh.654321.3)
650             ...
651 \end{alltt}
652
653
654 This example uses \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} for the section group
655 because the included declarations are not independently
656 visible as global entities.
657
658
659 \subsubsection{C Example}
660
661 The C++ example in this Section might appear to be equally
662 valid as a C example. However, it is prudent to include
663 a \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit} in the primary unit (see Figure 84)
664 with an \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute that refers to the proper unit
665 in the section group.
666
667 \textit{The C rules for consistency of global (file scope) symbols
668 across compilations are less strict than for C++; inclusion
669 of the import unit attribute assures that the declarations of
670 the proper section group are considered before declarations
671 from other compilations.}
672
673
674 \section{Using Type Units}
675 \label{app:usingtypeunits}
676
677 A large portion of debug information is type information, and
678 in a typical compilation environment, many types are duplicated
679 many times. One method of controlling the amount of duplication
680 is separating each type into a separate 
681 addtoindex{.debug\_types} section
682 and arranging for the linker to recognize and eliminate
683 duplicates at the individual type level.
684
685 Using this technique, each substantial type definition is
686 placed in its own individual section, while the remainder
687 of the DWARF information (non-type information, incomplete
688 type declarations, and definitions of trivial types) is
689 placed in the usual debug information section. In a typical
690 implementation, the relocatable object file may contain one
691 of each of these debug sections:
692
693 \begin{alltt}
694 \addtoindex{.debug\_abbrev}
695 \addtoindex{.debug\_info}
696 \addtoindex{.debug\_line}
697 \end{alltt}
698
699 and any number of these additional sections:
700
701 \begin{alltt}
702 \addtoindex{.debug\_types}
703 \end{alltt}
704
705 As discussed in the previous section 
706 (Section \refersec{app:usingcompilationunits}), 
707 many
708 linkers today support the concept of a COMDAT group or
709 linkonce section. The general idea is that a ``key'' can be
710 attached to a section or a group of sections, and the linker
711 will include only one copy of a section group (or individual
712 section) for any given key. For 
713 \addtoindex{.debug\_types} sections, the
714 key is the type signature formed from the algorithm given in
715 Section \refersec{datarep:typesignaturecomputation}.
716
717 \subsection{Signature Computation Example}
718 \label{app:signaturecomputationexample}
719
720 As an example, consider a C++ header file 
721 containing the type definitions shown
722 in Section \refersec{app:typesignatureexamplescsource}.
723
724 \subsubsection{ Type signature examples: C++ source}
725 \label{app:typesignatureexamplescsource}
726 \begin{lstlisting}
727 namespace N {
728
729  struct B;
730
731  struct C {
732      int x;
733      int y;
734  };
735
736  class A {
737    public:
738      A(int v);
739      int v();
740    private:
741      int v_;
742      struct A *next;
743      struct B *bp;
744      struct C c;
745  };
746
747  }
748 \end{lstlisting}
749
750 Next, consider one possible representation of the DWARF
751 information that describes the type “struct C” as shown
752 in 
753 \refersec{app:typesignaturecomputation1dwarfrepresentation}:
754
755 \subsubsection{Type signature  computation 1: DWARF representation}
756 \label{app:typesignaturecomputation1dwarfrepresentation}
757 % We keep the : (colon) away from the attribute so tokenizing in the python tools
758 % does not result in adding : into the attribute name.
759 \begin{alltt}
760   \livelink{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit}
761       \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} : \livelink{chap:DWLANGCplusplus}{DW\-\_LANG\-\_C\-\_plus\-\_plus} (4)
762     \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
763         \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "N"
764 L1:
765       \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
766           \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "C"
767           \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} : 8
768           \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
769           \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 5
770         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
771             \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "x"
772             \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
773             \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 6
774             \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L2
775             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} : 0
776         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
777             \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "y"
778             \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
779             \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 7
780             \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L2
781             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} : 4
782 L2:
783      \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
784          \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} : 4
785          \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} : \livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed}
786          \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "int"
787 \end{alltt}
788
789 In computing a signature for the type N::C, flatten the type
790 description into a byte stream according to the procedure
791 outlined in 
792 Section \refersec{datarep:typesignaturecomputation}.
793 The result is shown in 
794 Section \refersec{app:typesignaturecomputation1flattenedbytestream}.
795
796 \subsubsection{Type signature  computation 1: flattened byte stream}
797 \label{app:typesignaturecomputation1flattenedbytestream}
798
799 \begin{alltt}
800 // Step 2: 'C' \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} "N"
801 0x43 0x39 0x4e 0x00
802 // Step 3: 'D' \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
803 0x44 0x13
804 // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "C"
805 0x41 0x03 0x08 0x43 0x00
806 // Step 4: 'A' \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 8
807 0x41 0x0b 0x0d 0x08
808 // Step 7: First child ("x")
809     // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
810     0x44 0x0d
811     // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "x"
812     0x41 0x03 0x08 0x78 0x00
813     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 0
814     0x41 0x38 0x0d 0x00
815     // Step 6: 'T' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#2)
816     0x54 0x49
817         // Step 3: 'D' \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
818         0x44 0x24
819         // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "int"
820         0x41 0x03 0x08 0x69 0x6e 0x74 0x00
821         // Step 4: 'A' \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 4
822         0x41 0x0b 0x0d 0x04
823         // Step 4: 'A' \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed}
824         0x41 0x3e 0x0d 0x05
825         // Step 7: End of \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type} "int"
826         0x00
827     // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "x"
828     0x00
829 // Step 7: Second child ("y")
830     // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
831     0x44 0x0d
832     // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "y"
833     0x41 0x03 0x08 0x78 0x00
834     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 4
835     0x41 0x38 0x0d 0x04
836     // Step 6: 'R' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#2)
837     0x52 0x49 0x02
838     // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "y"
839     0x00
840 // Step 7: End of \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} "C"
841 0x00
842 \end{alltt}
843
844 Running an MD5 hash over this byte stream, and taking the
845 low\dash order 64 bits, yields the final signature: 
846 0xd28081e8 dcf5070a.
847
848 Next, consider a representation of the DWARF information that
849 describes the type ``class A'' as shown in 
850 Section \refersec{app:typesignaturecomputation2dwarfrepresentation}.
851
852
853 \subsubsection{Type signature  computation 2: DWARF representation}
854 \label{app:typesignaturecomputation2dwarfrepresentation}
855
856 \begin{alltt}
857   \livelink{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit}
858       \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language} : \livelink{chap:DWLANGCplusplus}{DW\-\_LANG\-\_C\-\_plus\-\_plus} (4)
859     \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
860           \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "N"
861 L1:
862         \livelink{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type}
863              \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "A"
864              \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} : 20
865              \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
866              \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 10
867            \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
868                 \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "v\_"
869                 \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
870                 \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 15
871                 \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L2
872                 \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} : 0
873                 \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} : \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
874           \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
875                \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "next"
876                \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
877                \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 16
878                \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L3
879                \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} : 4
880                \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} : \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
881           \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
882                \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "bp"
883                \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
884                \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 17
885                \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L4
886                \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} : 8
887                \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} : \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
888           \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
889                \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "c"
890                \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
891                \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 18
892                \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : 0xd28081e8 dcf5070a (signature for struct C)
893                \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} : 12
894                \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} : \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
895        \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
896            \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} : 1
897            \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "A"
898            \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
899            \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 12
900            \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} : 1
901         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
902            \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L3
903            \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} : 1
904         \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
905            \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L2
906        \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
907            \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} : 1
908            \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "v"
909            \livelink{chap:DWATdeclfile}{DW\-\_AT\-\_decl\-\_file} : 1
910            \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} : 13
911            \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L2
912            \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} : 1
913          \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}
914            \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L3
915            \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} : 1
916 L2:
917     \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
918          \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} : 4
919          \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} : \livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed}
920          \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "int"
921 L3:
922     \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
923          \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L1
924 L4:
925     \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
926          \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : reference to L5
927     \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace}
928          \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "N"
929 L5:
930        \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
931            \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "B"
932            \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} : 1
933 \end{alltt}
934
935 In this example, the structure types N::A and N::C have each
936 been placed in separate type units.  For N::A, the actual
937 definition of the type begins at label L1. The definition
938 involves references to the int base type and to two pointer
939 types. The information for each of these referenced types is
940 also included in this type unit, since base types and pointer
941 types are trivial types that are not worth the overhead of a
942 separate type unit. The last pointer type contains a reference
943 to an incomplete type N::B, which is also included here as
944 a declaration, since the complete type is unknown and its
945 signature is therefore unavailable. There is also a reference
946 to N::C, using 
947 \livelink{chap:DWFORMrefsig8}{DW\-\_FORM\-\_ref\-\_sig8} to refer to the type signature
948 for that type.
949
950 In computing a signature for the type N::A, flatten the type
951 description into a byte stream according to the procedure
952 outlined in 
953 Section \refersec{datarep:typesignaturecomputation}.
954 The result is shown in 
955 Section \refersec{app:typesignatureexample2flattenedbytestream}.
956
957 \subsubsection{Type signature example 2: flattenedbytestream}
958 \label{app:typesignatureexample2flattenedbytestream}
959 % DWARF4 had a \livelink{chap:DWATnamespace}{DW_AT_namespace} below, 
960 % but this error is fixed here to be \livelink{chap:DWTAGnamespace}{DW_TAG_namespace}.
961 \begin{alltt}
962 // Step 2: 'C' \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} "N"
963 0x43 0x39 0x4e 0x00
964 // Step 3: 'D' \livelink{chap:DWTAGclasstype}{DW\-\_TAG\-\_class\-\_type}
965 0x44 0x02
966 // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "A"
967 0x41 0x03 0x08 0x41 0x00
968 // Step 4: 'A' \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 20
969 0x41 0x0b 0x0d 0x14
970 // Step 7: First child ("v\_")
971     // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
972     0x44 0x0d
973     // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "v\_"
974     0x41 0x03 0x08 0x76 0x5f 0x00
975     // Step 4: 'A' \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
976     0x41 0x32 0x0d 0x03
977     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 0
978     0x41 0x38 0x0d 0x00
979     // Step 6: 'T' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#2)
980     0x54 0x49
981         // Step 3: 'D' \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
982         0x44 0x24
983         // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "int"
984         0x41 0x03 0x08 0x69 0x6e 0x74 0x00
985         // Step 4: 'A' \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 4
986         0x41 0x0b 0x0d 0x04
987         // Step 4: 'A' \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed}
988         0x41 0x3e 0x0d 0x05
989         // Step 7: End of \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type} "int"
990         0x00
991     // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "v\_"
992     0x00
993 // Step 7: Second child ("next")
994     // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
995     0x44 0x0d
996     // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "next"
997     0x41 0x03 0x08 0x6e 0x65 0x78 0x74 0x00
998     // Step 4: 'A' \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
999     0x41 0x32 0x0d 0x03
1000     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 4
1001     0x41 0x38 0x0d 0x04
1002     // Step 6: 'T' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#3)
1003     0x54 0x49
1004         // Step 3: 'D' \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
1005         0x44 0x0f
1006         // Step 5: 'N' \livelink{chap:DWATtype}{DW\-\_AT\-\_type}
1007         0x4e 0x49
1008         // Step 5: 'C' \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} "N" 'E'
1009         0x43 0x39 0x4e 0x00 0x45
1010         // Step 5: "A"
1011         0x41 0x00
1012         // Step 7: End of \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
1013         0x00
1014     // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "next"
1015     0x00
1016 // Step 7: Third child ("bp")
1017     // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
1018     0x44 0x0d
1019     // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "bp"
1020     0x41 0x03 0x08 0x62 0x70 0x00
1021     // Step 4: 'A' \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
1022     0x41 0x32 0x0d 0x03
1023     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 8
1024     0x41 0x38 0x0d 0x08
1025     // Step 6: 'T' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#4)
1026     0x54 0x49
1027         // Step 3: 'D' \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
1028 0x44 0x0f
1029         // Step 5: 'N' \livelink{chap:DWATtype}{DW\-\_AT\-\_type}
1030         0x4e 0x49
1031         // Step 5: 'C' \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} "N" 'E'
1032         0x43 0x39 0x4e 0x00 0x45
1033         // Step 5: "B"
1034         0x42 0x00
1035         // Step 7: End of \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}
1036         0x00
1037     // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "next"
1038     0x00
1039 // Step 7: Fourth child ("c")
1040     // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
1041     0x44 0x0d
1042     // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "c"
1043     0x41 0x03 0x08 0x63 0x00
1044     // Step 4: 'A' \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} \livelink{chap:DWACCESSprivate}{DW\-\_ACCESS\-\_private}
1045     0x41 0x32 0x0d 0x03
1046     // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 12
1047     0x41 0x38 0x0d 0x0c
1048     // Step 6: 'T' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#5)
1049     0x54 0x49
1050         // Step 2: 'C' \livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} "N"
1051         0x43 0x39 0x4e 0x00
1052         // Step 3: 'D' \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type}
1053         0x44 0x13
1054         // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "C"
1055         0x41 0x03 0x08 0x43 0x00
1056         // Step 4: 'A' \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 8
1057         0x41 0x0b 0x0d 0x08
1058         // Step 7: First child ("x")
1059             // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
1060             0x44 0x0d
1061             // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "x"
1062             0x41 0x03 0x08 0x78 0x00
1063             // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 0
1064             0x41 0x38 0x0d 0x00
1065             // Step 6: 'R' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#2)
1066             0x52 0x49 0x02
1067             // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "x"
1068             0x00
1069         // Step 7: Second child ("y")
1070             // Step 3: 'D' \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
1071             0x44 0x0d
1072             // Step 4: 'A' \livelink{chap:DWATname}{DW\-\_AT\-\_name} \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} "y"
1073             0x41 0x03 0x08 0x79 0x00
1074             // Step 4: 'A' \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} 4
1075             0x41 0x38 0x0d 0x04
1076             // Step 6: 'R' \livelink{chap:DWATtype}{DW\-\_AT\-\_type} (type \#2)
1077             0x52 0x49 0x02
1078             // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "y"
1079             0x00
1080         // Step 7: End of \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} "C"
1081         0x00
1082     // Step 7: End of \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} "c"
1083     0x00
1084 // Step 7: Fifth child ("A")
1085     // Step 3: 'S' \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} "A"
1086     0x53 0x2e 0x41 0x00
1087 // Step 7: Sixth child ("v")
1088     // Step 3: 'S' \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram} "v"
1089     0x53 0x2e 0x76 0x00
1090 // Step 7: End of \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} "A"
1091 0x00
1092 \end{alltt}
1093
1094 Running an MD5 hash over this byte stream, and taking the
1095 low-order 64 bits, yields the final signature: 0xd6d160f5
1096 5589f6e9.
1097
1098
1099 A source file that includes this header file may declare a
1100 variable of type N::A, and its DWARF information may look
1101 that shown in 
1102 Section \refersec{app:typesignatureexampleusage}.
1103
1104
1105 \subsubsection{Type signature example usage}
1106 \label{app:typesignatureexampleusage}
1107
1108 \begin{alltt}
1109   \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
1110   ...
1111   \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
1112     ...
1113     \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
1114       \livelink{chap:DWATname}{DW\-\_AT\-\_name} : "a"
1115       \livelink{chap:DWATtype}{DW\-\_AT\-\_type} : (signature) 0xd6d160f5 5589f6e9
1116       \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} : ...
1117     ...
1118 \end{alltt}
1119
1120 \subsection{Type Signature Computation Grammar}
1121 \label{app:typesignaturecomputationgrammar}
1122
1123 This section
1124 presents a semi-formal grammar that may aid in understanding
1125 how the bytes of the flattened type description are formed
1126 during the type signature computation algorithm of Section
1127 Section \refersec{datarep:typesignaturecomputation}. 
1128
1129
1130 \begin{alltt}
1131 signature
1132     : opt-context debug-entry attributes children
1133
1134 opt-context           // Step 2
1135     : 'C' tag-code string opt-context
1136     : empty
1137
1138 debug-entry           // Step 3
1139     : 'D' tag-code
1140
1141 attributes            // Steps 4, 5, 6
1142     : attribute attributes
1143     : empty
1144
1145 attribute
1146     : 'A' at-code form-encoded-value     // Normal attributes
1147     : 'N' at-code opt-context 'E' string // Reference to type
1148                                          // by name
1149     : 'R' at-code back-ref               // Back-reference 
1150                                          // to visited type
1151     : 'T' at-code signature              // Recursive type
1152 children             //  Step 7
1153     : child children
1154     : '\\0'
1155
1156 child
1157     : 'S' tag-code string
1158     : signature
1159 tag-code
1160     : <ULEB128>
1161 at-code
1162     : <ULEB128>
1163 form-encoded-value
1164     : \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata} value
1165     : \livelink{chap:DWFORMflag}{DW\-\_FORM\-\_flag} value
1166     : \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string} string
1167     : \livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block} \nolink{block}
1168 \livelink{chap:DWFORMstring}{DW\-\_FORM\-\_string}
1169     : '\\x08'
1170 \livelink{chap:DWFORMblock}{DW\-\_FORM\-\_block}
1171     : '\\x09'
1172 \livelink{chap:DWFORMflag}{DW\-\_FORM\-\_flag}
1173     : '\\x0c'
1174 \livelink{chap:DWFORMsdata}{DW\-\_FORM\-\_sdata}
1175     : '\\x0d'
1176 value
1177     : <SLEB128>
1178 \nolink{block}
1179     : <ULEB128> <fixed-length-block>
1180                       // The ULEB128 gives the length of the \nolink{block}
1181 back-ref
1182     : <ULEB128>
1183 string
1184     : <null-terminated-string>
1185 empty
1186     :
1187 \end{alltt}
1188
1189
1190 \section{Summary of Compression Techniques}
1191 \label{app:summaryofcompressiontechniques}
1192 \subsection{\#include compression}
1193 \label{app:includecompression}
1194
1195 C++ has a much greater problem than C with the number and
1196 size of the headers included and the amount of data in each,
1197 but even with C there is substantial header file information
1198 duplication.
1199
1200 A reasonable approach is to put each header file in its own
1201 section group, using the naming rules mentioned above. The
1202 section groups are marked to ensure duplicate removal.
1203
1204 All data instances and code instances (even if they came
1205 from the header files above) are put into non-section group
1206 sections such as the base object file 
1207 \addtoindex{.debug\_info} section.
1208
1209 \subsection{Eliminating function duplication}
1210 \label{app:eliminatingfunctionduplication}
1211
1212
1213 Function templates (C++) result in code for the same template
1214 instantiation being compiled into multiple archives or
1215 relocatable objects. The linker wants to keep only one of a
1216 given entity. The DWARF description, and everything else for
1217 this function, should be reduced to just a single copy.
1218
1219 For each such code group (function template in this example)
1220 the compiler assigns a name for the group which will match
1221 all other instantiations of this function but match nothing
1222 else. The section groups are marked to ensure duplicate
1223 removal, so that the second and subsequent definitions seen
1224 by the static linker are simply discarded.
1225
1226
1227 References to other 
1228 \addtoindex{.debug\_info} sections follow the approach
1229 suggested above, but the naming rule might be slightly
1230 different in that the 
1231 \begin{alltt}
1232 <file-designator> 
1233 \end{alltt}
1234 should be interpreted
1235 as a 
1236 \begin{alltt}
1237 <function-designator>.
1238 \end{alltt}
1239
1240
1241
1242 \subsection{Single-function-per-DWARF-compilation-unit}
1243 \label{app:singlefunctionperdwarfcompilationunit}
1244
1245 Section groups can help make it easy for a linker to completely
1246 remove unused functions.
1247
1248 Such section groups are not marked for duplicate removal,
1249 since the functions are not duplicates of anything.
1250
1251 Each function is given a compilation unit and a section
1252 group. Each such compilation unit is complete, with its own
1253 text, data, and DWARF sections.
1254
1255 There will also be a compilation unit that has the file\dash level
1256 declarations and definitions. Other per\dash function compilation
1257 unit DWARF information (
1258 \addtoindex{.debug\_info}) points to this common
1259 file\dash level compilation unit using \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}.
1260
1261 Section groups can use \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} and internal labels
1262 (section\dash relative relocations) to refer to the main object
1263 file sections, as the section groups here are either deleted
1264 as unused or kept. There is no possibility (aside from error)
1265 of a group from some other compilation being used in place
1266 of one of these groups.
1267
1268
1269 \subsection{Inlining and out-of-line-instances}
1270 \label{app:inliningandoutoflineinstances}
1271
1272 Abstract instances and concrete-out-of-line instances may be
1273 put in distinct compilation units using section groups. This
1274 makes possible some useful duplicate DWARF elimination.
1275
1276 \textit{No special provision for eliminating class duplication
1277 resulting from template instantiation is made here, though
1278 nothing prevents eliminating such duplicates using section
1279 groups.}
1280
1281
1282 \subsection{Separate Type Units}
1283 \label{app:separatetypeunits}
1284
1285 Each complete declaration of a globally-visible type can be
1286 placed in its own separate type section, with a group key
1287 derived from the type signature. The linker can then remove
1288 all duplicate type declarations based on the key.
1289