Changes to add index entries completing all of them up
authorDavid Anderson <davea42@earthlink.net>
Sun, 23 Sep 2012 21:35:36 +0000 (14:35 -0700)
committerDavid Anderson <davea42@earthlink.net>
Sun, 23 Sep 2012 21:35:36 +0000 (14:35 -0700)
through 'abstract'.  In 4.1 Latex.
Not quite half of the first page of index entries
done once these committed.

Working through the abstract instance examples it was
natural to do some of the
concrete instance example indexing too.

Explained in READMEindexing how to get < and > characters to print.

dwarf5/READMEindexing
dwarf5/latexdoc/compression.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/examples.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/programscope.tex

index 3cac1ea..dfa45ba 100644 (file)
@@ -60,6 +60,10 @@ a math character.
 \addtoindexi{address selection}{address selection|see{base address selection}}
 
 
+Use \textgreater  and \textless to represent < and >
+in indexes (and other contexts).  For example
+       \textless caf\textgreater   results in <caf>
+oddly enough.
 
 
 ---Linking
index 892b46a..da4d351 100644 (file)
@@ -1269,7 +1269,10 @@ of one of these groups.
 \subsection{Inlining and out-of-line-instances}
 \label{app:inliningandoutoflineinstances}
 
-Abstract instances and concrete-out-of-line instances may be
+Abstract instances
+\addtoindexx{abstract instance}
+\addtoindexx{concrete out-of-line instance}
+and concrete-out-of-line instances may be
 put in distinct compilation units using section groups. This
 makes possible some useful duplicate DWARF elimination.
 
index 1d3555b..e00ba5c 100644 (file)
@@ -125,6 +125,8 @@ is available in the run\dash time linker’s data structures.}
 \section{32-Bit and 64-Bit DWARF Formats}
 \label{datarep:32bitand64bitdwarfformats}
 
+\addtoindexx{32-bit DWARF format}
+\addtoindexx{64-bit DWARF format}
 There are two closely related file formats. In the 32\dash bit DWARF
 format, all values that represent lengths of DWARF sections
 and offsets relative to the beginning of DWARF sections are
@@ -268,10 +270,12 @@ followed by a \livelink{chap:DWTAGtypeunit}{DW\-\_TAG\-\_type\-\_unit} entry, to
 its children.
 
 Each debugging information entry begins with a code that
-represents an entry in a separate abbreviations table. This
+represents an entry in a separate 
+\addtoindex{abbreviations table}. This
 code is followed directly by a series of attribute values.
 
-The appropriate entry in the abbreviations table guides the
+The appropriate entry in the 
+\addtoindex{abbreviations table} guides the
 interpretation of the information contained directly in the
 \addtoindex{.debug\_info} or 
 \addtoindex{.debug\_types} section.
@@ -469,7 +473,9 @@ attributes with this form, the attribute value itself in the
 \addtoindex{.debug\_types}
 section begins with an unsigned
 LEB128 number that represents its form. This allows producers
-to choose forms for particular attributes dynamically,
+to choose forms for particular attributes 
+\addtoindexx{abbreviations table!dynamic forms in}
+dynamically,
 without having to add a new entry to the abbreviations table.
 
 The abbreviations for a given compilation unit end with an
index c3f0855..c10d2e8 100644 (file)
@@ -12,6 +12,7 @@ various aspects of the DWARF debugging information format.
 
 Figure \refersec{fig:compilationunitsandabbreviationstable}
 depicts the relationship of the abbreviations tables contained
+\addtoindexx{abbreviations table!example}
 \addtoindexx{.debug\_abbrev example}
 \addtoindexx{.debug\_info example}
 in the \addtoindex{.debug\_abbrev}
@@ -1349,7 +1350,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")
@@ -1396,7 +1397,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
@@ -1449,36 +1450,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.
@@ -1488,7 +1501,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")
@@ -1582,12 +1595,16 @@ 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},
@@ -1608,13 +1625,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
@@ -1638,7 +1659,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")
@@ -1685,7 +1706,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
@@ -1750,7 +1771,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)
index b1237cf..c93a612 100644 (file)
@@ -270,7 +270,7 @@ actually declared in the source} \\
 &\livelink{chap:DWATimportnamespaceusingdeclaration}{Namespace using declaration} \\
 &\livelink{chap:DWATimportnamespaceusingdirective}{Namespace using directive} \\
 \livetarg{chap:DWATinline}{DW\-\_AT\-\_inline}
-&\livelink{chap:DWATinlineabstracttinstance}{Abstract instance} \\
+&\livelinki{chap:DWATinlineabstracttinstance}{Abstract instance}{abstract instance} \\
 &\livelink{chap:DWATinlineinlinedsubroutine}{Inlined subroutine} \\
 \livetarg{chap:DWATisoptional}{DW\-\_AT\-\_is\-\_optional}
 &\livelink{chap:DWATisoptionaloptionalparameter}{Optional parameter} \\
index bc880e4..2d6fc32 100644 (file)
@@ -1405,14 +1405,20 @@ its address size must match the address size here.
 The size of a segment selector in this CIE and any FDEs that
 use it, in bytes.
 
-\item  code\_alignment\_factor (unsigned LEB128) \\
-A constant that is factored out of all advance location
+\item  \addtoindex{code\_alignment\_factor} (unsigned LEB128) \\
+\addtoindex{code alignment factor}
+A 
+\addtoindexx{\textless caf\textgreater|see{code alignment factor}}
+constant that is factored out of all advance location
 instructions (see 
 Section \refersec{chap:rowcreationinstructions}).
 
 
-\item  data\_alignment\_factor (signed LEB128) \\
-A constant that is factored out of certain offset instructions
+\item  \addtoindex{data\_alignment\_factor} (signed LEB128) \\
+\addtoindexx{data alignment factor}
+A 
+\addtoindexx{\textless daf\textgreater|see{data alignment factor}}
+constant that is factored out of certain offset instructions
 (see below). The resulting value is  \textit{(operand *
 data\_alignment\_factor)}.
 
@@ -1529,7 +1535,8 @@ with the opcode) that represents a constant delta. The required
 action is to create a new table row with a location value that
 is computed by taking the current entry’s location value
 and adding the value of 
-\textit{delta * code\_alignment\_factor}. All
+\textit{delta * \addtoindex{code\_alignment\_factor}}. 
+All
 other values in the new row are initially identical to the
 current row
 
@@ -1569,7 +1576,7 @@ an unsigned LEB128 value representing a register number and a
 signed LEB128 factored offset. This instruction is identical
 to \livelink{chap:DWCFAdefcfa}{DW\-\_CFA\-\_def\-\_cfa} except that the second operand is signed
 and factored. The resulting offset is factored\_offset *
-data\_alignment\_factor.
+\addtoindex{data\_alignment\_factor}.
 
 
 \item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_register} \\
@@ -1596,7 +1603,8 @@ The \livetarg{chap:DWCFAdefcfaoffsetsf}{DW\-\_CFA\-\_def\-\_cfa\-\_offset\-\_sf}
 LEB128 operand representing a factored offset. This instruction
 is identical to \livelink{chap:DWCFAdefcfaoffset}{DW\-\_CFA\-\_def\-\_cfa\-\_offset} except that the
 operand is signed and factored. The resulting offset is
-factored\_offset * data\_alignment\_factor. This operation
+factored\_offset * \addtoindex{data\_alignment\_factor}.
+This operation
 is valid only if the current CFA rule is defined to use a
 register and offset.
 
@@ -1635,7 +1643,7 @@ constant representing a factored offset. The required action
 is to change the rule for the register indicated by the
 register number to be an offset(N) rule where the value of
 N is 
-\textit{factored offset * data\_alignment\_factor.}
+\textit{factored offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_offset\-\_extended} \\
 The \livetarg{chap:DWCFAoffsetextended}{DW\-\_CFA\-\_offset\-\_extended} instruction takes two unsigned
@@ -1649,7 +1657,7 @@ an unsigned LEB128 value representing a register number and a
 signed LEB128 factored offset. This instruction is identical
 to \livelink{chap:DWCFAoffsetextended}{DW\-\_CFA\-\_offset\-\_extended} except that the second operand is
 signed and factored. The resulting offset is 
-\textit{factored\_offset * data\_alignment\_factor}.
+\textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_val\-\_offset} \\
 The \livetarg{chap:DWCFAvaloffset}{DW\-\_CFA\-\_val\-\_offset} instruction takes two unsigned
@@ -1657,7 +1665,7 @@ LEB128 operands representing a register number and a
 factored offset. The required action is to change the rule
 for the register indicated by the register number to be a
 val\_offset(N) rule where the value of N is 
-\textit{factored\_offset * data\_alignment\_factor}.
+\textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_val\-\_offset\-\_sf} \\
 The \livetarg{chap:DWCFAvaloffsetsf}{DW\-\_CFA\-\_val\-\_offset\-\_sf} instruction takes two operands: an
@@ -1665,7 +1673,7 @@ unsigned LEB128 value representing a register number and a
 signed LEB128 factored offset. This instruction is identical
 to \livelink{chap:DWCFAvaloffset}{DW\-\_CFA\-\_val\-\_offset} except that the second operand is signed
 and factored. The resulting offset is 
-\textit{factored\_offset * data\_alignment\_factor}.
+\textit{factored\_offset * \addtoindex{data\_alignment\_factor}}.
 
 \item \textbf{DW\-\_CFA\-\_register} \\
 The \livetarg{chap:DWCFAregister}{DW\-\_CFA\-\_register} instruction takes two unsigned LEB128
index 1700caf..128508c 100644 (file)
@@ -1025,13 +1025,18 @@ Any debugging information entry that is owned (either
 directly or indirectly) by a debugging information entry
 that contains the 
 \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute is referred to
-as an ``abstract instance entry.'' Any subroutine entry
+\addtoindexx{abstract instance!entry}
+as an ``abstract instance entry.'' 
+Any subroutine entry
 that contains a \livelink{chap:DWATinline}{DW\-\_AT\-\_inline} attribute whose value is other
-than \livelink{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined} is known as 
+than \livelink{chap:DWINLnotinlined}{DW\-\_INL\-\_not\-\_inlined}
+is known as 
+\addtoindexx{abstract instance!root}
 an ``abstract instance root.'' 
 Any set of abstract instance entries that are all
 children (either directly or indirectly) of some abstract
 instance root, together with the root itself, is known as
+\addtoindexx{abstract instance!tree}
 an ``abstract instance tree.'' However, in the case where
 an abstract instance tree is nested within another abstract
 instance tree, the entries in the nested abstract instance
@@ -1039,6 +1044,7 @@ tree are not considered to be entries in the outer abstract
 instance tree.
 
 Each abstract instance root is either part of a larger
+\addtoindexx{abstract instance!root}
 tree (which gives a context for the root) or uses
 \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} to refer to the declaration in context.
 
@@ -1178,6 +1184,7 @@ are specific to the concrete instance (but omitted in the
 abstract instance). In place of these omitted attributes, each
 \hypertarget{chap:DWATabstractorigininlineinstance}
 concrete inlined instance entry 
+\addtoindexx{abstract origin attribute}
 has a 
 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
 attribute that may be used to obtain the missing information
@@ -1194,6 +1201,7 @@ they may usually be omitted from any entry that has an abstract
 origin attribute.
 
 For each pair of entries that are associated via a
+\addtoindexx{abstract origin attribute}
 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin} attribute, both members of the pair
 have the same tag. So, for example, an entry with the tag
 \livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable} can only be associated with another entry
@@ -1210,7 +1218,9 @@ tree. There are a few exceptions:
 
 \begin{enumerate}[1.]
 \item An entry in the concrete instance tree may be omitted if
-it contains only a \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin} attribute and either
+it contains only a 
+\addtoindexx{abstract origin attribute}
+\livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin} attribute and either
 has no children, or its children are omitted. Such entries
 would provide no useful information. In C\dash like languages,
 such entries frequently include types, including structure,
@@ -1238,6 +1248,7 @@ not correspond to entries in the abstract instance tree
 to describe new entities that are specific to a particular
 inlined expansion. In that case, they will not have associated
 entries in the abstract instance tree, should not contain
+\addtoindexx{abstract origin attribute}
 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin} attributes, and must contain all their
 own attributes directly. This allows an abstract instance tree
 to omit debugging information entries for anonymous entities
@@ -1265,7 +1276,9 @@ concrete inlined instance of that subroutine (as described in
 the preceding section). The representation of such a concrete
 % It is critical that the hypertarget and livelink be
 % separated to avoid problems with latex.
-out\dash of\dash line instance 
+out\dash of\dash line 
+\addtoindexx{abstract origin attribute}
+instance 
 \hypertarget{chap:DWATabstractoriginoutoflineinstance}
 makes use of 
 \livelink{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
@@ -1309,6 +1322,8 @@ nested subroutine.
 
 For an inlined subroutine nested within another inlined
 subroutine, the following rules apply to their abstract and
+\addtoindexx{abstract instance!nested}
+\addtoindexx{concrete instance!nested}
 concrete instance trees:
 
 \begin{enumerate}[1.]