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 
 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}
 \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}
 \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
 \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
 ==== ...
 ==== 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
 \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.]
 
 
 \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
 (\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).
 
 
 \item  A means of identifying a section group (giving it a name).
 
@@ -259,7 +261,8 @@ during compilation.
 
 \end{itemize}
 
 
 \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
 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.
 
 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.
 
 \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
 \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
 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
 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
 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
 \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})
 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]
 \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}
     \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
 
 
     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}
 
 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 .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")
     \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}
 \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}
     \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
 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.
 
 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}
 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}
 \end{alltt}
 
 and any number of these additional sections:
 
 \begin{alltt}
-.debug\_types
+\addtoindex{.debug\_types}
 \end{alltt}
 
 As discussed in the previous section 
 \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
 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}.
 
 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
 
 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}
 
 \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.
 
 
 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}
 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
 
 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
 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