Adds index entries for all .debug_* and a couple other
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index 59f12f4..892b46a 100644 (file)
@@ -48,40 +48,41 @@ to suggest traditional contents as a way of explaining the
 approach, not to be limiting.}
 
 A traditional relocatable object output 
-from a single compilation might contain sections named:
+from a single compilation might contain sections 
+named:
 \begin{alltt}
-    .data
-    .text
-    .debug\_info
-    .debug\_abbrev
-    .debug\_line
-    .debug\_aranges
+    \addtoindex{.data}
+    \addtoindex{.text}
+    \addtoindex{.debug\_info}
+    \addtoindex{.debug\_abbrev}
+    \addtoindex{.debug\_line}
+    \addtoindex{.debug\_aranges}
 \end{alltt}
 A relocatable object from a compilation system 
 attempting duplicate DWARF elimination might
 contain sections as in:
 
 \begin{alltt}
-    .data
-    .text
-    .debug\_info
-    .debug\_abbrev
-    .debug\_line
-    .debug\_aranges
+    \addtoindex{.data}
+    \addtoindex{.text}
+    \addtoindex{.debug\_info}
+    \addtoindex{.debug\_abbrev}
+    \addtoindex{.debug\_line}
+    \addtoindex{.debug\_aranges}
 \end{alltt}
 
 followed (or preceded, the order is not significant) 
 by a series of section groups:
 \begin{alltt}
 ==== Section group 1
-    .debug\_info
-    .debug\_abbrev
-    .debug\_line
+    \addtoindex{.debug\_info}
+    \addtoindex{.debug\_abbrev}
+    \addtoindex{.debug\_line}
 ==== ...
 ==== Section group N
-    .debug\_info
-    .debug\_abbrev
-    .debug\_line
+    \addtoindex{.debug\_info}
+    \addtoindex{.debug\_abbrev}
+    \addtoindex{.debug\_line}
 \end{alltt}
 
 where each section group might or might not contain executable
@@ -128,12 +129,13 @@ facilities such as simple relocations) are:
 
 \begin{enumerate}[1.]
 
-\item A means of referencing from inside one .debug\_info
-compilation unit to another .debug\_info compilation unit
+\item A means of referencing from inside one \addtoindex{.debug\_info}
+compilation unit to another 
+\addtoindex{.debug\_info} compilation unit
 (\livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} provides this).
 
 \item A means of having multiple contributions to specific sections
-(for example, .debug\_info, and so on) in a single object file.
+(for example, \addtoindex{.debug\_info}, and so on) in a single object file.
 
 \item  A means of identifying a section group (giving it a name).
 
@@ -259,7 +261,8 @@ during compilation.
 
 \end{itemize}
 
-In general, every point in the section group .debug\_info that
+In general, every point in the section group 
+\addtoindex{.debug\_info} that
 could be referenced from outside by any compilation unit must
 normally have an external name generated for it in the linker
 symbol table, whether the current compilation references all
@@ -360,16 +363,18 @@ Use
 unit's debugging information entries to those of another
 compilation unit.
 
-When referencing into a removable section group .debug\_info
-from another .debug\_info (from anywhere), the
+When referencing into a removable section group 
+\addtoindex{.debug\_info}
+from another \addtoindex{.debug\_info} (from anywhere), the
 \begin{alltt}
 <prefix>.<file-designator>.<gid-number>.<die-number>
 \end{alltt}
 name should be used for an external symbol and a relocation
 generated based on that name.
 
-When referencing into a non-section group .debug\_info,
-from another .debug\_info (from anywhere) 
+When referencing into a non-section group 
+\addtoindex{.debug\_info},
+from another \addtoindex{.debug\_info} (from anywhere) 
 \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} is
 still the form to be used, but a section\dash relative relocation
 generated by use of a non-exported name (often called an
@@ -383,12 +388,16 @@ This section provides several examples in order to have a
 concrete basis for discussion.
 
 In these examples, the focus is on the arrangement of DWARF
-information into sections (specifically the .debug\_info
+information into sections (specifically the 
+\addtoindex{.debug\_info}
 section) and the naming conventions used to achieve references
 into section groups. In practice, all of the examples that
-follow involve DWARF sections other than just .debug\_info
-(for example, .debug\_line, .debug\_aranges, or others);
-however, only the .debug\_info section is shown to keep the
+follow involve DWARF sections other than just 
+\addtoindex{.debug\_info}
+(for example, \addtoindex{.debug\_line}, 
+\addtoindex{.debug\_aranges}, or others);
+however, only the \addtoindex{.debug\_info}
+section is shown to keep the
 examples compact and easier to read.
 
 The grouping of sections into a named set is shown, but the means for achieving this in terms of
@@ -436,7 +445,7 @@ wa.h.
 \begin{alltt}
 ==== Section group name:
     my.compiler.company.cpp.wa.h.123456
-== section .debug\_info
+== section \addtoindex{.debug\_info}
 DW.cpp.wa.h.123456.1: ! linker global symbol
     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
         \livelink{chap:DWATlanguage}{DW\-\_AT\-\_language}(\livelink{chap:DWLANGCplusplus}{DW\-\_LANG\-\_C\-\_plus\-\_plus})
@@ -467,7 +476,7 @@ in the section group shown above.
 \begin{alltt}
 == section .text
     [generated code for function f]
-== section .debug\_info
+== section \addtoindex{.debug\_info}
     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
 .L1:                   ! local (non-linker) symbol
         \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type}
@@ -527,7 +536,7 @@ corresponding to the included file CommonStuff.fh.
 
     my.f90.company.f90.CommonStuff.fh.654321
 
-== section .debug\_info
+== section \addtoindex{.debug\_info}
 
 DW.myf90.CommonStuff.fh.654321.1:    ! linker global symbol
     \livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit}
@@ -574,7 +583,7 @@ shows the sections for the primary compilation unit.
 == section .text
     [code for function Foo]
 
-== section .debug\_info
+== section \addtoindex{.debug\_info}
     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
         \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("Foo")
@@ -619,7 +628,7 @@ Section \refersec{app:duplicateeliminationexample2companiondwarf}.
 \label{app:duplicateeliminationexample2companiondwarf}
 
 \begin{alltt}
-== section .debug\_info
+== section \addtoindex{.debug\_info}
     \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}(F90\$main)
         \livelink{chap:DWTAGbasetype}{DW\-\_TAG\-\_base\-\_type}
@@ -668,7 +677,8 @@ from other compilations.}
 A large portion of debug information is type information, and
 in a typical compilation environment, many types are duplicated
 many times. One method of controlling the amount of duplication
-is separating each type into a separate .debug\_types section
+is separating each type into a separate 
+addtoindex{.debug\_types} section
 and arranging for the linker to recognize and eliminate
 duplicates at the individual type level.
 
@@ -681,15 +691,15 @@ implementation, the relocatable object file may contain one
 of each of these debug sections:
 
 \begin{alltt}
-.debug\_abbrev
-.debug\_info
-.debug\_line
+\addtoindex{.debug\_abbrev}
+\addtoindex{.debug\_info}
+\addtoindex{.debug\_line}
 \end{alltt}
 
 and any number of these additional sections:
 
 \begin{alltt}
-.debug\_types
+\addtoindex{.debug\_types}
 \end{alltt}
 
 As discussed in the previous section 
@@ -699,7 +709,8 @@ linkers today support the concept of a COMDAT group or
 linkonce section. The general idea is that a ``key'' can be
 attached to a section or a group of sections, and the linker
 will include only one copy of a section group (or individual
-section) for any given key. For .debug\_types sections, the
+section) for any given key. For 
+\addtoindex{.debug\_types} sections, the
 key is the type signature formed from the algorithm given in
 Section \refersec{datarep:typesignaturecomputation}.
 
@@ -1192,7 +1203,8 @@ section groups are marked to ensure duplicate removal.
 
 All data instances and code instances (even if they came
 from the header files above) are put into non-section group
-sections such as the base object file .debug\_info section.
+sections such as the base object file 
+\addtoindex{.debug\_info} section.
 
 \subsection{Eliminating function duplication}
 \label{app:eliminatingfunctionduplication}
@@ -1212,7 +1224,8 @@ removal, so that the second and subsequent definitions seen
 by the static linker are simply discarded.
 
 
-References to other .debug\_info sections follow the approach
+References to other 
+\addtoindex{.debug\_info} sections follow the approach
 suggested above, but the naming rule might be slightly
 different in that the 
 \begin{alltt}
@@ -1241,7 +1254,8 @@ text, data, and DWARF sections.
 
 There will also be a compilation unit that has the file\dash level
 declarations and definitions. Other per\dash function compilation
-unit DWARF information (.debug\_info) points to this common
+unit DWARF information (
+\addtoindex{.debug\_info}) points to this common
 file\dash level compilation unit using \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}.
 
 Section groups can use \livelink{chap:DWFORMrefaddr}{DW\-\_FORM\-\_ref\-\_addr} and internal labels