Indexing i and j is done.
[dwarf-doc.git] / dwarf5 / latexdoc / examples.tex
index d05a4da..7907baa 100644 (file)
@@ -12,8 +12,13 @@ various aspects of the DWARF debugging information format.
 
 Figure \refersec{fig:compilationunitsandabbreviationstable}
 depicts the relationship of the abbreviations tables contained
-in the .debug\_abbrev section to the information contained in
-the .debug\_info section. Values are given in symbolic form,
+\addtoindexx{abbreviations table!example}
+\addtoindexx{.debug\_abbrev example}
+\addtoindexx{.debug\_info example}
+in the \addtoindex{.debug\_abbrev}
+section to the information contained in
+the \addtoindex{.debug\_info}
+section. Values are given in symbolic form,
 where possible.
 
 The figure corresponds to the following two trivial source files:
@@ -33,7 +38,7 @@ typedef char* strp;
 %\centering
 \begin{minipage}{0.4\textwidth}
 \centering
-Compilation Unit 1: .debug\_info
+Compilation Unit 1: \addtoindex{.debug\_info}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -74,7 +79,7 @@ e2
 %
 %
 \end{framed}
-Compilation Unit 2: .debug\_info
+Compilation Unit 2: \addtoindex{.debug\_info}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -101,7 +106,7 @@ e2
 \hfill
 \begin{minipage}{0.4\textwidth}
 \centering
-Abbreviation Table: .debug\_abbrev
+Abbreviation Table: \addtoindex{.debug\_abbrev}
 \begin{framed}
 \scriptsize
 \begin{alltt}
@@ -160,7 +165,8 @@ using DWARF.
 
 \subsection{Fortran 90 Example}
 \label{app:fortran90example}
-Consider the Fortran 90 source fragment in 
+Consider the \addtoindex{Fortran 90} source fragment in 
+\addtoindexx{array type entry!examples}
 Figure \refersec{fig:fortran90examplesourcefragment}.
 
 \begin{figure}[here]
@@ -179,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,7 +206,9 @@ 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}
@@ -241,14 +252,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}
@@ -276,7 +290,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}
@@ -379,7 +395,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:
 
@@ -484,7 +502,8 @@ would be different.
 \label{app:adaexample}
 
 Figure \refersec{fig:adaexamplesourcefragment}
-illustrates two kinds of Ada parameterized array, one embedded in a record.
+illustrates two kinds of \addtoindex{Ada} 
+parameterized array, one embedded in a record.
 
 
 \begin{figure}[here]
@@ -503,7 +522,8 @@ OBJ2B : REC2;
 \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
@@ -558,7 +578,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)
@@ -582,7 +602,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}
@@ -608,8 +628,8 @@ of this example and therefore not shown.
 
 The Pascal source in 
 Figure \refersec{fig:packedrecordexamplesourcefragment}
-is used to illustrate the representation of packed unaligned bit
-fields.
+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
@@ -658,9 +678,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\$)
@@ -680,7 +700,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\$)
@@ -1103,7 +1123,7 @@ for the foo subroutine
 is shown in 
 Table \refersec{tab:callframeinformationexampleconceptualmatrix}.
 Corresponding fragments from the
-.debug\_frame section are shown in 
+\addtoindex{.debug\_frame} section are shown in 
 Table \refersec{tab:callframeinformationexamplecommoninformationentryencoding}.
 
 The following notations apply in 
@@ -1241,6 +1261,7 @@ fde+44 && \\
 The pseudo\dash source in 
 Figure \refersec{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
@@ -1345,7 +1366,7 @@ Section \refersec{app:inliningexample1concreteinstance}.
 \label{app:inliningexample1abstractinstance}
 \begin{alltt}
     ! Abstract instance for OUTER
-    !
+    ! \addtoindexx{abstract instance!example}
 OUTER.AI.1.1:
     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
@@ -1392,7 +1413,7 @@ INNER.AI.1.3:
 \label{app:inliningexample1concreteinstance}
 \begin{alltt}
 ! Concrete instance for call "OUTER(7)"
-!
+! \addtoindexx{concrete instance!example}
 OUTER.CI.1.1:
     \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
         ! No name
@@ -1445,36 +1466,48 @@ INNER.CI.1.3:
 
 In the second alternative we assume that subprogram INNER
 is not inlinable for some reason, but subprogram OUTER is
-inlinable. Each concrete inlined instance of OUTER has its
-own normal instance of INNER. The abstract instance for OUTER,
+inlinable. 
+\addtoindexx{concrete instance!example}
+Each concrete inlined instance of OUTER has its
+own normal instance of INNER. 
+The abstract instance for OUTER,
+\addtoindexx{abstract instance!example}
 which includes INNER, is shown in 
 Section \refersec{app:inliningexample2abstractinstance}.
 
 Note that the debugging information in this Figure differs from
 that in 
 Section \refersec{app:inliningexample1abstractinstance}
-in that INNER lacks a \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute
+in that INNER lacks a 
+\livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute
 and therefore is not a distinct abstract instance. INNER
 is merely an out\dash of\dash line routine that is part of OUTER’s
 abstract instance. This is reflected in the Figure 70 by
+\addtoindexx{abstract instance!example}
 the fact that the labels for INNER use the substring OUTER
 instead of INNER.
 
-A resulting concrete inlined instance of OUTER is shown in
+A resulting 
+\addtoindexx{concrete instance!example}
+concrete inlined instance of OUTER is shown in
 Section \refersec{app:inliningexample2concreteinstance}.
 
 Notice in 
 Section \refersec{app:inliningexample2concreteinstance}.
 that OUTER is expanded as a concrete
+\addtoindexx{concrete instance!example}
 inlined instance, and that INNER is nested within it as a
 concrete out\dash of\dash line subprogram. Because INNER is cloned
 for each inline expansion of OUTER, only the invariant
 attributes of INNER 
 (for example, \livelink{chap:DWATname}{DW\-\_AT\-\_name}) are specified
 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.
 
+\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}) are specified in 
+each concrete instance of OUTER.
+\addtoindexx{concrete instance!example}
 The several calls of INNER within OUTER are compiled as normal
 calls to the instance of INNER that is specific to the same
 instance of OUTER that contains the calls.
@@ -1484,7 +1517,7 @@ instance of OUTER that contains the calls.
 \label{app:inliningexample2abstractinstance}
 \begin{alltt}
     ! Abstract instance for OUTER
-    !
+    ! \addtoindex{abstract instance}
 OUTER.AI.2.1:
     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
@@ -1578,17 +1611,30 @@ OUTER.CI.2.6:
 
 In the third approach, one normal subprogram for INNER is
 compiled which is called from all concrete inlined instances of
+\addtoindexx{concrete instance!example}
+\addtoindexx{abstract instance!example}
 OUTER. The abstract instance for OUTER is shown in 
 Section \refersec{app:inliningexample3abstractinstance}.
 
 The most distinctive aspect of that Figure is that subprogram
 INNER exists only within the abstract instance of OUTER,
 and not in OUTER’s concrete instance. In the abstract
+\addtoindexx{concrete instance!example}
+\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
@@ -1604,13 +1650,17 @@ INNER at all; the representation of INNER does not vary across
 instances of OUTER and the abstract instance of OUTER includes
 the complete description of INNER, so that the description of
 INNER may be (and for reasons of space efficiency, should be)
-omitted from each concrete instance of OUTER.
+omitted from each 
+\addtoindexx{concrete instance!example}
+concrete instance of OUTER.
 
 There is one aspect of this approach that is problematical from
 the DWARF perspective. The single compiled instance of INNER
 is assumed to access up\dash level variables of OUTER; however,
 those variables may well occur at varying positions within
-the frames that contain the concrete inlined instances. A
+the frames that contain the 
+\addtoindexx{concrete instance!example}
+concrete inlined instances. A
 compiler might implement this in several ways, including the
 use of additional compiler generated parameters that provide
 reference parameters for the up\dash level variables, or a compiler
@@ -1634,7 +1684,7 @@ for accessing purposes.)
 \label{app:inliningexample3abstractinstance}
 \begin{alltt}
     ! Abstract instance for OUTER
-    !
+    ! \addtoindexx{abstract instance!example}
 OUTER.AI.3.1:
     \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
         \livelink{chap:DWATname}{DW\-\_AT\-\_name}("OUTER")
@@ -1681,7 +1731,7 @@ OUTER.AI.3.6:
 \label{app:inliningexample3concreteinstance}
 \begin{alltt}
     ! Concrete instance for call "OUTER(7)"
-    !
+    ! \addtoindexx{concrete instance!example}
 OUTER.CI.3.1:
     \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
         ! No name
@@ -1746,7 +1796,7 @@ Section \refersec{app:constantexpressionsdwarfdescription}.
             \livelink{chap:DWATname}{DW\-\_AT\-\_name}("x")
             \livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to "int")
       ! Concrete instance for square(9)
-      !
+      ! \addtoindexx{concrete instance!example}
 20\$: \livelink{chap:DWTAGinlinedsubroutine}{DW\-\_TAG\-\_inlined\-\_subroutine}
         \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}(reference to 10\$)
         \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}(present)