Misc corrections Chpt 6 thru App A
[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex
index c10d2e8..c3b1954 100644 (file)
@@ -165,8 +165,9 @@ using DWARF.
 
 \subsection{Fortran 90 Example}
 \label{app:fortran90example}
-Consider the Fortran 90 source fragment in 
-Figure \refersec{fig:fortran90examplesourcefragment}.
+Consider the \addtoindex{Fortran 90} source fragment in 
+\addtoindexx{array type entry!examples}
+Figure \referfol{fig:fortran90examplesourcefragment}.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -184,7 +185,10 @@ end do
 \end{figure}
 
 For allocatable and pointer arrays, it is essentially required
-by the Fortran 90 semantics that each array consist of two
+by the \addtoindex{Fortran 90} semantics that each array consist of 
+\addtoindexx{descriptor!array}
+two
+\addtoindexx{array!descriptor for}
 parts, which we here call 1) the descriptor and 2) the raw
 data. (A descriptor has often been called a dope vector in
 other contexts, although it is often a structure of some kind
@@ -197,12 +201,14 @@ the ``variable'' is allocated or associated).
 
 For concreteness, suppose that a descriptor looks something
 like the C structure in 
-Figure \refersec{fig:fortran90exampledescriptorrepresentation}.
+Figure \referfol{fig:fortran90exampledescriptorrepresentation}.
 Note, however, that it is
 a property of the design that 1) a debugger needs no builtin
 knowledge of this structure and 2) there does not need to
 be an explicit representation of this structure in the DWARF
-input to the debugger.
+input to the 
+\addtoindexx{Fortran 90}
+debugger.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -219,7 +225,8 @@ struct desc {
     } dims[63];
 };
 \end{lstlisting}
-\caption{Fortran 90 example: descriptor representation} \label{fig:fortran90exampledescriptorrepresentation}
+\caption{Fortran 90 example: descriptor representation}
+\label{fig:fortran90exampledescriptorrepresentation}
 \end{figure}
 
 
@@ -246,14 +253,17 @@ to the “raw data” (the real data, the only thing around
 that can be the object).
 
 If an object has a descriptor, then the DWARF type for that
-object will have a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. If an object
+object will have a 
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. If an object
 does not have a descriptor, then usually the DWARF type for the
-object will not have a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}. (See the following
-Ada example for a case where the type for an object without
+object will not have a 
+\livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}. 
+(See the following
+\addtoindex{Ada} example for a case where the type for an object without
 a descriptor does have a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location} attribute. In
 that case the object doubles as its own descriptor.)
 
-The Fortran 90 derived type array\_ptr can now be redescribed
+The \addtoindex{Fortran 90} derived type array\_ptr can now be redescribed
 in C\dash like terms that expose some of the representation as in
 
 \begin{lstlisting}
@@ -281,7 +291,9 @@ within an entity of the given type
 \end{enumerate}
 
 
-The DWARF description is shown in 
+The DWARF description is shown 
+\addtoindexx{Fortran 90}
+in 
 Section \refersec{app:fortran90exampledwarfdescription}.
 
 \subsection{Fortran 90 example: DWARF description}
@@ -384,7 +396,9 @@ Section \refersec{app:fortran90exampledwarfdescription}.
 \subsection{Fortran 90 example continued: DWARF description}
 \label{app:fortran90examplecontinueddwarfdescription}
 
-Suppose the program is stopped immediately following completion
+Suppose 
+\addtoindexx{Fortran 90 example}
+the program is stopped immediately following completion
 of the do loop. Suppose further that the user enters the
 following debug command:
 
@@ -488,8 +502,9 @@ would be different.
 \subsection{Ada Example}
 \label{app:adaexample}
 
-Figure \refersec{fig:adaexamplesourcefragment}
-illustrates two kinds of Ada parameterized array, one embedded in a record.
+Figure \referfol{fig:adaexamplesourcefragment}
+illustrates two kinds of \addtoindex{Ada} 
+parameterized array, one embedded in a record.
 
 
 \begin{figure}[here]
@@ -504,11 +519,13 @@ end record;
 
 OBJ2B : REC2;
 \end{lstlisting}
-\caption{Ada 90 example: source fragment} \label{fig:adaexamplesourcefragment}
+\caption{Ada 90 example: source fragment}
+\label{fig:adaexamplesourcefragment}
 \end{figure}
 
 VEC1 illustrates an (unnamed) array type where the upper bound
-of the first and only dimension is determined at runtime. Ada
+of the first and only dimension is determined at runtime. 
+\addtoindex{Ada}
 semantics require that the value of an array bound is fixed at
 the time the array type is elaborated (where elaboration refers
 to the runtime executable aspects of type processing). For
@@ -563,7 +580,7 @@ of this example and therefore not shown.
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("M")
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
 12\$: \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
-        ! No name, default (Ada) order, default stride
+        ! No name, default (\addtoindex{Ada}) order, default stride
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
 13\$:    \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
@@ -587,7 +604,7 @@ of this example and therefore not shown.
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to subtype TEENY at 21\$)
             \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location}(constant 0)
 28\$:   \livelink{chap:DWTAGarraytype}{DW\-\_TAG\-\_array\-\_type}
-            ! No name, default (Ada) order, default stride
+            ! No name, default (\addtoindex{Ada}) order, default stride
             ! Default data location
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to INTEGER)
 29\$:       \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type}
@@ -611,10 +628,11 @@ of this example and therefore not shown.
 \subsection{Pascal Example}
 \label{app:pascalexample}
 
-The Pascal source in 
-Figure \refersec{fig:packedrecordexamplesourcefragment}
-is used to illustrate the representation of packed unaligned bit
-fields.
+The Pascal \addtoindexx{Pascal example} source in 
+Figure \referfol{fig:packedrecordexamplesourcefragment}
+is used to illustrate the representation of packed unaligned
+\addtoindex{bit fields}.
+
 \begin{figure}[here]
 \begin{lstlisting}
 TYPE T : PACKED RECORD ! bit size is 2
@@ -630,7 +648,8 @@ F4 : PACKED ARRAY [0..1] OF T; ! bit offset is 33
 F7 : T; ! bit offset is 37
 END;
 \end{lstlisting}
-\caption{Packed record example: source fragment} \label{fig:packedrecordexamplesourcefragment}
+\caption{Packed record example: source fragment}
+\label{fig:packedrecordexamplesourcefragment}
 \end{figure}
 
 The DWARF representation in 
@@ -663,9 +682,9 @@ Section \refersec{chap:datamemberentries}.
             \livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(0)
             \livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(1)
         \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}(2)
-        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4)
+        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4) \addtoindexx{bit size attribute}
 23\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} ! anonymous type for V
-        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(39)
+        \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(39) \addtoindexx{bit size attribute}
         \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F1")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 10\$)
@@ -685,7 +704,7 @@ Section \refersec{chap:datamemberentries}.
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("F7")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 20\$) ! type T
             \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}(37)
-            \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(2) ! may be omitted
+            \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(2) \addtoindexx{bit size attribute}! may be omitted
      \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("V")
         \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 23\$)
@@ -698,8 +717,10 @@ Section \refersec{chap:datamemberentries}.
 
 
 The C++ example in 
-Figure \refersec{fig:namespaceexamplesourcefragment}
-is used to illustrate the representation of namespaces.
+Figure \referfol{fig:namespaceexamplesourcefragment}
+is used 
+\addtoindexx{namespace (C++)!example}
+to illustrate the representation of namespaces.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -737,12 +758,13 @@ int Foo::myfunc(int a)
     return myfunc2(3) + j + i + a + 2;
 }
 \end{lstlisting}
-\caption{Namespace example: source fragment} \label{fig:namespaceexamplesourcefragment}
+\caption{Namespace example: source fragment}
+\label{fig:namespaceexamplesourcefragment}
 \end{figure}
 
 
 The DWARF representation in 
-Section \refersec{app:namespaceexampledwarfdescription}
+Section \referfol{app:namespaceexampledwarfdescription}
 is appropriate.
 
 \subsection{Namespace example: DWARF description}
@@ -829,7 +851,7 @@ is appropriate.
 \label{app:memberfunctionexample}
 
 Consider the member function example fragment in 
-Figure \refersec{fig:memberfunctionexamplesourcefragment}.
+Figure \referfol{fig:memberfunctionexamplesourcefragment}.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -841,7 +863,8 @@ class A
 };
 void A::func1(int x) {}
 \end{lstlisting}
-\caption{Member function example: source fragment} \label{fig:memberfunctionexamplesourcefragment}
+\caption{Member function example: source fragment}
+\label{fig:memberfunctionexamplesourcefragment}
 \end{figure}
 
 
@@ -878,7 +901,7 @@ is appropriate.
             \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("func1")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
-            \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 8\$)
+            \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 8\$) \addtoindexx{object pointer attribute}
                 ! References a formal parameter in this 
                 ! member function
             ...
@@ -899,7 +922,7 @@ is appropriate.
              \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}
              \livelink{chap:DWATname}{DW\-\_AT\-\_name}("func2")
              \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 1\$)
-             \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 11\$)
+             \livelink{chap:DWATobjectpointer}{DW\-\_AT\-\_object\-\_pointer}(reference to 11\$) \addtoindexx{object pointer attribute}
              ! References a formal parameter in this 
              ! member function
              ...
@@ -929,7 +952,7 @@ is appropriate.
 
 Consider the simple source file and the resulting machine
 code for the Intel 8086 processor in 
-Figure \refersec{fig:linenumberprogramexamplemachinecode}.
+Figure \referfol{fig:linenumberprogramexamplemachinecode}.
 
 \begin{figure}[here]
 \begin{lstlisting}
@@ -953,12 +976,21 @@ Figure \refersec{fig:linenumberprogramexamplemachinecode}.
     0x24c: ret
 7: 0x24d:
 \end{lstlisting}
-\caption{Line number program example: machine code} \label{fig:linenumberprogramexamplemachinecode}
+\caption{Line number program example: machine code}
+\label{fig:linenumberprogramexamplemachinecode}
 \end{figure}
 
 Suppose the line number program header includes the following
-(header fields not needed below are not shown):
-
+(header fields not 
+needed 
+\addtoindexx{line\_base}
+below 
+\addtoindexx{line\_range}
+are 
+\addtoindexx{opcode\_base}
+not 
+\addtoindexx{minumum\_instruction\_length}
+shown):
 
 
 \begin{alltt}
@@ -970,7 +1002,7 @@ line_range                15
 \end{alltt}
 
 
-Figure \refersec{tab:linenumberprogramexampleoneencoding}
+Table \referfol{tab:linenumberprogramexampleoneencoding}
 shows one encoding of the line number program, which occupies
 12 bytes (the opcode SPECIAL(m,n) indicates the special opcode
 generated for a line increment of m and an address increment
@@ -980,7 +1012,8 @@ of n).
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lll}
-  \caption{Line number program example: one encoding} \label{tab:linenumberprogramexampleoneencoding} \\
+  \caption{Line number program example: one encoding}
+  \label{tab:linenumberprogramexampleoneencoding} \\
   \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
 \endfirsthead
   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
@@ -1000,7 +1033,7 @@ SPECIAL(1, 7)&0x73 & \\
 \end{centering}
 
 
-Table \refersec{tab:linenumberprogramexamplealternateencoding}
+Table \referfol{tab:linenumberprogramexamplealternateencoding}
 shows an alternate 
 encoding of the same program using 
 standard opcodes to advance
@@ -1010,7 +1043,8 @@ this encoding occupies 22 bytes.
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lll}
-  \caption{Line number program example: alternate encoding} \label{tab:linenumberprogramexamplealternateencoding} \\
+  \caption{Line number program example: alternate encoding} 
+  \label{tab:linenumberprogramexamplealternateencoding} \\
   \hline \\ \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream \\ \hline
 \endfirsthead
   \bfseries Opcode &\bfseries Operand &\bfseries Byte Stream\\ \hline
@@ -1071,9 +1105,8 @@ stack pointer (R7) is the same as the CFA
 
 \end{itemize}
 
-The following 
-(Figure refersec{fig:callframeinformationexamplemachinecodefragments}
-are two code fragments from a subroutine called
+Figure \referfol{fig:callframeinformationexamplemachinecodefragments}
+shows two code fragments from a subroutine called
 foo that uses a frame pointer (in addition to the stack
 pointer). The first column values are byte addresses. 
 % The \space is so we get a space after >
@@ -1098,15 +1131,15 @@ foo+76 add R7, R7, <fs>        ; Deallocate frame
 foo+80 jump R1 ; Return
 foo+84
 \end{lstlisting}
-\caption{Call frame information example: machine code fragments} \label{fig:callframeinformationexamplemachinecodefragments}
+\caption{Call frame information example: machine code fragments}
+\label{fig:callframeinformationexamplemachinecodefragments}
 \end{figure}
 
 
 An abstract table 
 (see Section \refersec{chap:structureofcallframeinformation}) 
-for the foo subroutine
-is shown in 
-Table \refersec{tab:callframeinformationexampleconceptualmatrix}.
+for the foo subroutine is shown in 
+Table \referfol{tab:callframeinformationexampleconceptualmatrix}.
 Corresponding fragments from the
 \addtoindex{.debug\_frame} section are shown in 
 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
@@ -1126,7 +1159,8 @@ Table \refersec{tab:callframeinformationexampleconceptualmatrix}:
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lllllllllll}
-  \caption{Call frame inforation example: conceptual matrix} \label{tab:callframeinformationexampleconceptualmatrix} \\
+  \caption{Call frame inforation example: conceptual matrix} 
+  \label{tab:callframeinformationexampleconceptualmatrix} \\
   \hline \\ \bfseries Location & \bfseries CFA & \bfseries R0 & \bfseries R1 & \bfseries R2 & \bfseries R3 & \bfseries R4 & \bfseries R5 & \bfseries R6 & \bfseries R7 & \bfseries R8 \\ \hline
 \endfirsthead
   \bfseries Location &\bfseries CFA &\bfseries R0 & \bfseries R1 & \bfseries R2 &\bfseries R3 &\bfseries R4 &\bfseries R5 &\bfseries R6 &\bfseries R7 &\bfseries R8\\ \hline
@@ -1154,7 +1188,8 @@ foo+80&[R7]+0&s&u&u&u&s&s&s&a&r1 \\
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{lll}
-  \caption{Call frame information example: common information entry encoding} \label{tab:callframeinformationexamplecommoninformationentryencoding} \\
+  \caption{Call frame information example: common information entry encoding} 
+  \label{tab:callframeinformationexamplecommoninformationentryencoding} \\
   \hline \\ \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
 \endfirsthead
   \bfseries Address &\bfseries Value &\bfseries Comment \\ \hline
@@ -1244,8 +1279,9 @@ fde+44 && \\
 \section{Inlining Examples}
 \label{app:inliningexamples}
 The pseudo\dash source in 
-Figure \refersec{fig:inliningexamplespseudosourcefragment}
+Figure \referfol{fig:inliningexamplespseudosourcefragment}
 is used to illustrate the
+\addtoindexx{inlined subprogram call!examples}
 use of DWARF to describe inlined subroutine calls. This
 example involves a nested subprogram INNER that makes uplevel
 references to the formal parameter and local variable of the
@@ -1269,7 +1305,8 @@ inline procedure OUTER (OUTER_FORMAL : integer) =
 !
 OUTER(7);
 \end{lstlisting}
-\caption{Inlining examples: pseudo-source fragmment} \label{fig:inliningexamplespseudosourcefragment}
+\caption{Inlining examples: pseudo-source fragmment} 
+\label{fig:inliningexamplespseudosourcefragment}
 \end{figure}
 
 
@@ -1474,10 +1511,10 @@ instead of INNER.
 A resulting 
 \addtoindexx{concrete instance!example}
 concrete inlined instance of OUTER is shown in
-Section \refersec{app:inliningexample2concreteinstance}.
+Section \referfol{app:inliningexample2concreteinstance}.
 
 Notice in 
-Section \refersec{app:inliningexample2concreteinstance}.
+Section \referfol{app:inliningexample2concreteinstance}.
 that OUTER is expanded as a concrete
 \addtoindexx{concrete instance!example}
 inlined instance, and that INNER is nested within it as a
@@ -1488,7 +1525,6 @@ attributes of INNER
 in the abstract instance of OUTER, and the low\dash level,
 \addtoindexx{abstract instance!example}
 instance\dash specific attributes of INNER (for example,
-
 \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}) are specified in 
 each concrete instance of OUTER.
 \addtoindexx{concrete instance!example}
@@ -1607,9 +1643,18 @@ and not in OUTER’s concrete instance. In the abstract
 \addtoindexx{abstract instance!example}
 instance of OUTER, the description of INNER has the full
 complement of attributes that would be expected for a
-normal subprogram. While attributes such as \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
-\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}, \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}, and so on, typically are omitted
-from an abstract instance because they are not invariant across
+normal subprogram. 
+While attributes such as 
+\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
+\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}, 
+\livelink{chap:DWATlocation}{DW\-\_AT\-\_location},
+and so on, typically are omitted
+\addtoindexx{high PC attribute}
+from 
+\addtoindexx{low PC attribute}
+an 
+\addtoindexx{location attribute}
+abstract instance because they are not invariant across
 instances of the containing abstract instance, in this case
 those same attributes are included precisely because they are
 invariant -- there is only one subprogram INNER to be described
@@ -1797,8 +1842,8 @@ Section \refersec{app:constantexpressionsdwarfdescription}.
 
 \section{Unicode Character Example}
 \label{app:unicodecharacterexample}
-
-Unicode character encodings can be described in DWARF as
+\addtoindexx{Unicode|see {\textit{also} UTF-8}}
+\addtoindex{Unicode} character encodings can be described in DWARF as
 illustrated in 
 Section \refersec{app:unicodecharacterexamplesub}.
 
@@ -1837,7 +1882,9 @@ char32_t chr_b = U'h';
 \label{app:typesafeenumerationexample}
 
 
-C++ type\dash safe enumerations can be described in DWARF as illustrated in 
+C++ type\dash safe enumerations 
+\addtoindexx{type-safe enumeration}
+can be described in DWARF as illustrated in 
 Section \refersec{app:ctypesafeenumerationexample}.
 
 \begin{lstlisting}
@@ -2002,7 +2049,9 @@ wrapper<int>.
 \section{Template Alias Examples}
 \label{app:templatealiasexample}
 
-C++ template aliases can be described in DWARF as illustrated in 
+C++ template aliases can be described in DWARF as illustrated 
+\addtoindexx{template alias example}
+in 
 Section \refersec{app:templatealiasexample1}
 and 
 Section \refersec{app:templatealiasexample2}.
@@ -2022,6 +2071,7 @@ Beta<long> b;
 
 
 \subsection{template alias example 1}
+\addtoindexx{template alias example 1}
 \label{app:templatealiasexample1}
 \begin{alltt}
 ! DWARF representation for variable 'b'
@@ -2064,6 +2114,7 @@ X<Z<int>> z;
 
 
 \subsection{template alias example 2}
+\addtoindexx{template alias example 2}
 \label{app:templatealiasexample2}
 \begin{alltt}
 ! DWARF representation for X<Y<int>>