Merge branch 'HEAD' of dwarfgit@dwarfstd.org:dwarf-doc.git
[dwarf-doc.git] / dwarf5 / latexdoc / compression.tex
index 66566f4..1aec7b6 100644 (file)
@@ -1,5 +1,5 @@
 \chapter[Compression (Informative)]{DWARF Compression and Duplicate Elimination (Informative)}
-\label{dwarfcompressionandduplicateeliminationinformative}
+\label{app:dwarfcompressionandduplicateeliminationinformative}
 
 % It seemed difficult to get close to the same layout and 
 % captioning as DWARF4 here with figures as they moved (floated)
@@ -11,9 +11,9 @@ can
 \addtoindexx{DWARF duplicate elimination}
 use a lot of disk space.
 
-This is especially true for C++, where the depth and complexity
+This is especially true for \addtoindex{C++}, where the depth and complexity
 of headers can mean that many, many (possibly thousands of)
-declarations are repeated in every compilation unit. C++
+declarations are repeated in every compilation unit. \addtoindex{C++}
 templates can also mean that some functions and their DWARF
 descriptions get duplicated.
 
@@ -51,7 +51,7 @@ but aside from the DWARF sections, the names are just meant
 to suggest traditional contents as a way of explaining the
 approach, not to be limiting.}
 
-A traditional relocatable object output 
+A traditional relocatable object output file
 from a single compilation might contain sections 
 named:
 \begin{alltt}
@@ -62,7 +62,7 @@ named:
     \dotdebugline{}
     \dotdebugaranges{}
 \end{alltt}
-A relocatable object from a compilation system 
+A relocatable object file from a compilation system 
 attempting duplicate DWARF elimination might
 contain sections as in:
 
@@ -144,23 +144,22 @@ linker (outside of DWARF itself, and normal object/linker
 facilities such as simple relocations) are:
 \begin{enumerate}[1. ]
 
-\item A means of referencing from inside one \dotdebuginfo{}
-compilation unit to another 
-\dotdebuginfo{} compilation unit
-(\DWFORMrefaddr{} provides this).
+\item A means to reference the \dotdebuginfo{} information 
+of one compilation unit from the \dotdebuginfo{} section of 
+another compilation unit (\DWFORMrefaddr{} provides this).
 
-\item A means of having multiple contributions to specific sections
-(for example, \dotdebuginfo{}, and so on) in a single object file.
+\item A means to combine multiple contributions to specific sections
+(for example, \dotdebuginfo{}) into a single object file.
 
-\item  A means of identifying a \addtoindex{section group} (giving it a name).
+\item  A means to identify a \addtoindex{section group} 
+(giving it a name).
 
-\item A means of identifying which sections go together to make
-up a \addtoindex{section group}, 
-so that the group can be treated as a unit
-(kept or discarded).
+\item A means to indicate which sections go together to make
+up a \addtoindex{section group}, so that the group can be 
+treated as a unit (kept or discarded).
 
-\item  A means of indicating how each \addtoindex{section group} should be
-processed by the linker.
+\item  A means to indicate how each \addtoindex{section group} 
+should be processed by the linker.
 
 \end{enumerate}
 
@@ -169,9 +168,10 @@ corresponds closely to the similarly named concepts in the
 ELF object file representation. 
 The notion of \addtoindex{section group} is
 an abstraction of common extensions of the ELF representation
-widely known as \doublequote{COMDATs} or \doublequote{COMDAT sections.} (Other
-object file representations provide COMDAT\dash style mechanisms as
-well.) There are several variations in the COMDAT schemes in
+widely known as 
+\doublequote{\COMDAT{}s} or \doublequote{\COMDAT{} sections.} (Other
+object file representations provide \COMDAT{}\dash style mechanisms as
+well.) There are several variations in the \COMDAT{} schemes in
 common use, any of which should be sufficient for the purposes
 of the 
 \addtoindexx{duplication elimination|see{DWARF duplicate elimination}}
@@ -233,7 +233,7 @@ the same
 \textless gid\dash number\textgreater,
 and
 
-\item  a non\dash matching output (say because of \texttt{\#defines})
+\item  a non-matching output (say because of \texttt{\#defines})
 generates a different 
 \textless gid\dash number\textgreater.
 \end{itemize}
@@ -253,12 +253,12 @@ corresponding to file wa.h
 above is given the name \texttt{my.compiler.company.cpp.wa.h.123456}.
 
 
-
+\needlines{4}
 \textbf{Debugging Information Entry Names}
 
 Global labels for 
 \addtoindexx{debugging information entry!ownership relation}
-debugging information entries (need explained
+debugging information entries (the need for which is explained
 below) within a \addtoindex{section group}
 can be given names of the form
 
@@ -299,7 +299,7 @@ symbol table, whether the current compilation references all
 those points or not.
 
 \textit{The completeness of the set of names generated is a
-quality\dash of\dash implementation issue.}
+quality-of-implementation issue.}
 
 It is up to the producer to ensure that if 
 \textless die\dash numbers\textgreater\ 
@@ -354,7 +354,7 @@ not a good candidate because the entities included are not
 necessarily file level entities.
 
 This also applies to \addtoindex{Fortran} INCLUDE lines when declarations
-are included into a procedure or module context.
+are included into a subprogram or module context.
 
 Consequently a compiler must use \DWTAGpartialunit{} (instead
 of \DWTAGcompileunit) 
@@ -450,7 +450,7 @@ the underlying object language is not (and varies from system to system).
 \subsubsection{C++ Example}
 
 The \addtoindex{C++} source 
-\addtoindexx{DWARF duplicate elimination!C++ example}
+\addtoindexx{DWARF duplicate elimination!examples}
 in 
 Figure \refersec{fig:duplicateeliminationexample1csource}
 is used to illustrate the DWARF
@@ -458,20 +458,20 @@ representation intended to allow duplicate elimination.
 
 \begin{figure}[ht]
 \textit{File wa.h}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 struct A {
    int i;
 };
-\end{lstlisting}
+\end{nlnlisting}
 \textit{File wa.c}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 #include "wa.h";
 int
 f(A &a)
 {
     return a.i + 2;
 }
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Duplicate elimination example \#1: C++ Source}
 \label{fig:duplicateeliminationexample1csource}
 \end{figure}
@@ -549,31 +549,52 @@ globally visible (in accordance with
 \DWTAGpartialunit{} 
 is not needed for the same reason.
 
+\needlines{6}
+\subsubsection{C Example}
+
+The \addtoindex{C++} example 
+\addtoindexx{DWARF duplicate elimination!examples}
+in this Section might appear to be equally
+valid as a \addtoindex{C} example. However, for \addtoindex{C} 
+it is prudent to include a \DWTAGimportedunit{}
+in the primary unit 
+(see Figure \refersec{fig:duplicateeliminationexample1primarycompilationunit})
+as well as an \DWATimport{} attribute that refers to the proper unit
+in the \addtoindex{section group}.
+
+\needlines{4}
+\textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
+across compilations are less strict than for \addtoindex{C++}; inclusion
+of the import unit attribute assures that the declarations of
+the proper \addtoindex{section group} are considered before declarations
+from other compilations.}
+
+
 \subsubsection{Fortran Example}
 
 
 For a \addtoindex{Fortran}
-\addtoindexx{DWARF duplicate elimination!Fortran example}
+\addtoindexx{DWARF duplicate elimination!examples}
 example, consider 
 Figure \refersec{fig:duplicateeliminationexample2fortransource}.
 
-\begin{figure}
+\begin{figure}[ht]
 \textit{File CommonStuff.f\hspace{1pt}h}
 \addtoindexx{Fortran}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 IMPLICIT INTEGER(A-Z)
 COMMON /Common1/ C(100)
 PARAMETER(SEVEN = 7)
-\end{lstlisting}
+\end{nlnlisting}
 
 \textit{File Func.f}
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 FUNCTION FOO (N)
 INCLUDE 'CommonStuff.fh'
 FOO = C(N + SEVEN)
 RETURN
 END
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Duplicate elimination example \#2: Fortran source} 
 \label{fig:duplicateeliminationexample2fortransource}
 \end{figure}
@@ -668,12 +689,12 @@ Figure \refersec{fig:duplicateeliminationexample2companionsource}
 
 \begin{figure}
 \textit{File Main.f} 
-\begin{lstlisting}[numbers=none]
+\begin{nlnlisting}
 INCLUDE 'CommonStuff.fh'
 C(50) = 8
 PRINT *, 'Result = ', FOO(50 - SEVEN)
 END
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Duplicate elimination example \#2: companion source }
 \label{fig:duplicateeliminationexample2companionsource}
 \end{figure}
@@ -721,26 +742,6 @@ because the included declarations are not independently
 visible as global entities.
 
 
-\needlines{6}
-\subsubsection{C++ Example}
-
-The \addtoindex{C++} example 
-\addtoindexx{DWARF duplicate elimination!C++ example}
-in this Section might appear to be equally
-valid as a \addtoindex{C} example. However, it is prudent to include
-a \DWTAGimportedunit{}
-in the primary unit 
-(see Figure \refersec{fig:duplicateeliminationexample1primarycompilationunit})
-with an \DWATimport{} attribute that refers to the proper unit
-in the \addtoindex{section group}.
-
-\textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
-across compilations are less strict than for C++; inclusion
-of the import unit attribute assures that the declarations of
-the proper \addtoindex{section group} are considered before declarations
-from other compilations.}
-
-
 \section{Using Type Units}
 \label{app:usingtypeunits}
 
@@ -748,7 +749,7 @@ 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 
-\dotdebugtypes{} section
+\COMDAT{} \dotdebuginfo{} section
 and arranging for the linker to recognize and eliminate
 duplicates at the individual type level.
 
@@ -766,23 +767,19 @@ of each of these debug sections:
 \dotdebugline{}
 \end{alltt}
 
-and any number of these additional sections:
-
-\begin{alltt}
-\dotdebugtypes{}
-\end{alltt}
+and any number of additional \COMDAT{} \dotdebuginfo{} sections
+containing type units.
 
 \needlines{5}
 As discussed in the previous section 
 (Section \refersec{app:usingcompilationunits}), 
 many
-linkers today support the concept of a COMDAT group or
+linkers today support the concept of a \COMDAT{} group or
 linkonce section. The general idea is that a \doublequote{key} can be
 attached to a section or a group of sections, and the linker
 will include only one copy of a \addtoindex{section group}
 (or individual section) for any given key. 
-For 
-\dotdebugtypes{} sections, the
+For \COMDAT{} \dotdebuginfo{} sections, the
 key is the \addtoindex{type signature}
 formed from the algorithm given in
 Section \refersec{datarep:typesignaturecomputation}.
@@ -796,8 +793,8 @@ consider a \addtoindex{C++} header file
 containing the type definitions shown
 in Figure \refersec{fig:typesignatureexamplescsource}.
 
-\begin{figure}[h]
-\begin{lstlisting}
+\begin{figure}[ht]
+\begin{nlnlisting}
 namespace N {
 
     struct B;
@@ -818,7 +815,7 @@ namespace N {
         struct C c;
     };
 }
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Type signature examples: C++ source}
 \label{fig:typesignatureexamplescsource}
 \end{figure}
@@ -911,7 +908,7 @@ Figure \refersec{fig:typesignaturecomputation1flattenedbytestream}.
     // Step 3: 'D' \DWTAGmember
     0x44 0x0d
     // Step 4: 'A' \DWATname \DWFORMstring "y"
-    0x41 0x03 0x08 0x78 0x00
+    0x41 0x03 0x08 0x79 0x00
     // Step 4: 'A' \DWATdatamemberlocation \DWFORMsdata 4
     0x41 0x38 0x0d 0x04
     // Step 6: 'R' \DWATtype (type \#2)
@@ -927,7 +924,7 @@ Figure \refersec{fig:typesignaturecomputation1flattenedbytestream}.
 \end{figure}
 
 \needlines{4}
-Running an \addtoindex{MD5 hash} over this byte stream, and taking the
+Running an \MDfive{} hash over this byte stream, and taking the
 low\dash order 64 bits, yields the final signature: 
 0xd28081e8 dcf5070a.
 
@@ -1028,7 +1025,7 @@ L5:
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-\vspace{2mm}
+\vspace{3mm}
 Figure~\ref{fig:typesignaturecomputation2dwarfrepresentation}: Type signature computation \#2: DWARF representation \textit{(concluded)}
 \end{center}
 \end{figure}
@@ -1049,17 +1046,8 @@ to an incomplete type \texttt{N::B}, which is also included here as
 a declaration, since the complete type is unknown and its
 signature is therefore unavailable. There is also a reference
 to \texttt{N::C}, using 
-\DWFORMrefsigeight{} to 
-refer to the type signature
-\addtoindexx{type signature}
-for that type.
-
-In computing a signature for the type \texttt{N::A}, flatten the type
-description into a byte stream according to the procedure
-outlined in 
-Section \refersec{datarep:typesignaturecomputation}.
-The result is shown in 
-Figure \refersec{fig:typesignatureexample2flattenedbytestream}.
+\DWFORMrefsigeight{} to refer to the type signature
+\addtoindexx{type signature} for that type.
 
 \begin{figure}
 \figurepart{1}{3}
@@ -1143,7 +1131,7 @@ Figure \refersec{fig:typesignatureexample2flattenedbytestream}.
     // Step 6: 'T' \DWATtype (type \#4)
     0x54 0x49
         // Step 3: 'D' \DWTAGpointertype
-0x44 0x0f
+        0x44 0x0f
         // Step 5: 'N' \DWATtype
         0x4e 0x49
         // Step 5: 'C' \DWTAGnamespace "N" 'E'
@@ -1164,7 +1152,7 @@ Figure \refersec{fig:typesignatureexample2flattenedbytestream}.
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-\vspace{2mm}
+\vspace{3mm}
 Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature example \#2: flattened byte stream \textit{(continued)}
 \end{center}
 \end{figure}
@@ -1222,22 +1210,28 @@ Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature exampl
 \end{alltt}
 \end{dwflisting}
 \begin{center}
-\vspace{2mm}
+\vspace{3mm}
 Figure~\ref{fig:typesignatureexample2flattenedbytestream}: Type signature example \#2: flattened byte stream \textit{(concluded)}
 \end{center}
 \end{figure}
 
-Running an \addtoindex{MD5 hash} over this byte stream, and taking the
+In computing a signature for the type \texttt{N::A}, flatten the type
+description into a byte stream according to the procedure
+outlined in 
+Section \refersec{datarep:typesignaturecomputation}.
+The result is shown in 
+Figure \refersec{fig:typesignatureexample2flattenedbytestream}.
+
+Running an \MDfive{} hash over this byte stream, and taking the
 low-order 64 bits, yields the final signature: 0xd6d160f5
 5589f6e9.
 
-
 A source file that includes this header file may declare a
 variable of type \texttt{N::A}, and its DWARF information may look
 like that shown in 
 Figure \refersec{fig:typesignatureexampleusage}.
 
-\begin{figure}
+\begin{figure}[ht]
 \begin{dwflisting}
 \begin{alltt}
   \DWTAGcompileunit
@@ -1265,7 +1259,7 @@ how the bytes of the flattened type description are formed
 during the type signature computation algorithm of
 Section \refersec{datarep:typesignaturecomputation}. 
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \begin{dwflisting}
 %FIXME: The index entries here with \addtoindexx are ineffective.
 \begin{alltt}
@@ -1286,7 +1280,7 @@ attribute
     : 'T' at-code signature              // Recursive type
 children                 //  Step 7
     : child children
-    : '0'
+    : '\textbackslash{}0'
 child
     : 'S' tag-code string
     : signature
@@ -1300,13 +1294,13 @@ form-encoded-value
     : \DWFORMstring string \addtoindexx{string class}
     : \DWFORMblock \nolink{block} \addtoindexx{block class}
 \DWFORMstring \addtoindexx{string class}
-    : 'x08'
+    : '\textbackslash{}x08'
 \DWFORMblock  \addtoindexx{block class}
-    : 'x09'
+    : '\textbackslash{}x09'
 \DWFORMflag \addtoindexx{flag class}
-    : 'x0c'
+    : '\textbackslash{}x0c'
 \DWFORMsdata \addtoindexx{constant class}
-    : 'x0d'
+    : '\textbackslash{}x0d'
 value
     : <SLEB128>
 \nolink{block}
@@ -1323,6 +1317,65 @@ empty
 \label{fig:typesignaturecomputationgrammar}
 \end{figure}
 
+\clearpage
+\subsection{Declarations Completing Non-Defining Declarations}
+\label{app:declarationscompletingnondefiningdeclarations}
+Consider a compilation unit that contains a definition of the member
+function \texttt{N::A::v()} from 
+Figure \refersec{fig:typesignatureexamplescsource}. 
+A possible representation of the
+debug information for this function in the compilation unit is shown
+in Figure \refersec{fig:completingedeclarationofamemberfunctiondwarf}.
+
+\begin{figure}[ht]
+\begin{dwflisting}
+\begin{alltt}
+  \DWTAGnamespace
+      \DWATname{} : "N"
+L1:
+    \DWTAGclasstype
+        \DWATname{} : "A"
+        \DWATdeclaration{} : true
+        \DWATsignature{} : 0xd6d160f5 5589f6e9
+L2:
+      \DWTAGsubprogram
+          \DWATexternal{} : 1
+          \DWATname{} : "v"
+          \DWATdeclfile{} : 1
+          \DWATdeclline{} : 13
+          \DWATtype{} : reference to L3
+          \DWATdeclaration{} : 1
+        \DWTAGformalparameter
+            \DWATtype{} : reference to L4
+            \DWATartificial{} : 1
+...
+L3:
+  \DWTAGbasetype
+      \DWATbytesize{} : 4
+      \DWATencoding{} : \DWATEsigned
+      \DWATname{} : "int"
+...
+L4:
+  \DWTAGpointertype
+      \DWATtype{} : reference to L1
+...
+  \DWTAGsubprogram
+      \DWATspecification{} : reference to L2
+      \DWATdeclfile{} : 2
+      \DWATdeclline{} : 25
+      \DWATlowpc{} : ...
+      \DWAThighpc{} : ...
+    \DWTAGlexicalblock
+    ...
+...
+\end{alltt}
+\end{dwflisting}
+\caption{Completing declaration of a member function: DWARF \mbox{encoding}}
+\label{fig:completingedeclarationofamemberfunctiondwarf}
+\end{figure}
+
+
+\clearpage
 \section{Summary of Compression Techniques}
 \label{app:summaryofcompressiontechniques}
 \subsection{\#include compression}
@@ -1353,7 +1406,7 @@ sections such as the base object file
 
 Function templates (C++) result in code for the same template
 instantiation being compiled into multiple archives or
-relocatable objects. The linker wants to keep only one of a
+relocatable object files. The linker wants to keep only one of a
 given entity. The DWARF description, and everything else for
 this function, should be reduced to just a single copy.
 
@@ -1376,7 +1429,6 @@ different in that the \texttt{\textless file-designator\textgreater}
 should be interpreted as a \texttt{\textless file-designator\textgreater}.
 
 
-
 \subsection{Single-function-per-DWARF-compilation-unit}
 \label{app:singlefunctionperdwarfcompilationunit}