Adds index entries for all the index entries in DW4 that
authorDavid Anderson <davea42@earthlink.net>
Mon, 17 Sep 2012 20:34:10 +0000 (13:34 -0700)
committerDavid Anderson <davea42@earthlink.net>
Mon, 17 Sep 2012 20:34:10 +0000 (13:34 -0700)
begin with 'address'
Also adds  two latex commands to simplify indexing.

dwarf5/READMEindexing
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/hint.txt
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/typeentries.tex

index e56ab2b..3cac1ea 100644 (file)
@@ -17,6 +17,7 @@ Of course the command also indexes the link.
 The actual command definitions in dwarf5.tex are:
 \newcommand{\addtoindex}[1]{#1\index{#1}}
 \newcommand{\addtoindexi}[2]{#1\index{#2}}
+\newcommand{\addtoindexx}[1]{\index{#2}}
 \newcommand{\noindex}[1]{#1}
 
 Where a word or phrase is to be indexed.
index b19d6cc..9675481 100644 (file)
@@ -306,7 +306,9 @@ in the 64\dash bit DWARF format, this is an 8\dash byte unsigned length
 
 \item address\_size (ubyte) \\
 A 1\dash byte unsigned integer representing the size in bytes of
+\addtoindexx{address\_size}
 an address on the target architecture. If the system uses
+\addtoindexx{address space!segmented}
 segmented addressing, this value represents the size of the
 offset portion of an address.
 
@@ -351,7 +353,9 @@ in the 64\dash bit DWARF format, this is an 8\dash byte unsigned length
 
 \item address\_size (ubyte) \\
 A 1\dash byte unsigned integer representing the size in bytes of
+\addtoindexx{address\_size}
 an address on the target architecture. If the system uses
+\addtoindexx{address space!segmented}
 segmented addressing, this value represents the size of the
 offset portion of an address.
 
@@ -487,10 +491,11 @@ their usage for the other classes.}
 Each possible form belongs to one or more of the following classes:
 
 \begin{itemize}
-\item address \\
+\item \livelinki{chap:DWATaddressclass}{address}{address class} \\
 Represented as an object of appropriate size to hold an
 address on the target machine 
-(\livetarg{chap:DWFORMaddr}{DW\-\_FORM\-\_addr}). The size is
+(\livetarg{chap:DWFORMaddr}{DW\-\_FORM\-\_addr}). 
+The size is
 encoded in the compilation unit header 
 (see Section \refersec{datarep:compilationunitheader}).
 This address is relocatable in a relocatable object file and
@@ -1497,7 +1502,9 @@ defined language.
 \section{Address Class Encodings}
 \label{datarep:addressclassencodings}
 
-The value of the common address class encoding 
+The value of the common 
+\addtoindexi{address}{address class!attribute encoding}
+class encoding 
 \livelink{chap:DWADDRnone}{DW\-\_ADDR\-\_none} is 0.
 
 
@@ -1730,7 +1737,9 @@ this is an 8\dash byte unsigned offset
 
 \item address\_size (ubyte) \\
 A 1\dash byte unsigned integer containing the size in bytes of an
+\addtoindexx{address\_size}
 address (or the offset portion of an address for segmented
+\addtoindexx{address space!segmented}
 addressing) on the target system.
 
 \item segment\_size (ubyte) \\
index d38eb84..9a2f8aa 100644 (file)
@@ -69,6 +69,8 @@ escapeinside={\%*}{*)}  % if you want to add a comment within your code
 % Generate a live link in the document
 % use like \livelink{chap:DWOPdup}{DW\-\_OP\-\_dup}
 \newcommand{\livelink}[2]{\hyperlink{#1}{#2}\index{#2} }
+% use when the index is different from the text and target.
+\newcommand{\livelinki}[3]{\hyperlink{#1}{#2}\index{#3} }
 % livetarg is the declaration this is the target of livelinks.
 % FIXME: we might want livetarg and livetargi  #2 to be \textbf{#2}
 \newcommand{\livetarg}[2]{\hypertarget{#1}{#2}\index{#2}}
@@ -89,6 +91,7 @@ escapeinside={\%*}{*)}  % if you want to add a comment within your code
 %For index entries.
 \newcommand{\addtoindex}[1]{#1\index{#1}}
 \newcommand{\addtoindexi}[2]{#1\index{#2}}
+\newcommand{\addtoindexx}[1]{\index{#1}}
 
 
 \begin{document}
index f84c3f7..a1fd70f 100644 (file)
@@ -488,7 +488,13 @@ of the entry to which the attribute is attached.
 
 \section{Target Addresses}
 \label{chap:targetaddresses}
-Many places in this document refer to the size of an address
+Many places in this document 
+refer
+\addtoindexx{address size|see{size of an address}}
+to the size 
+\addtoindexx{address!size of an|see{size of an address}}
+of an
+\addtoindexi{address}{size of an address}
 on the target architecture (or equivalently, target machine)
 to which a DWARF description applies. For processors which
 can be configured to have different address sizes or different
@@ -647,10 +653,14 @@ stack entry, the second entry becomes the top of the stack,
 and the third entry becomes the second entry.
 
 \item  \livetarg{chap:DWOPderef}{DW\-\_OP\-\_deref} \\
-The \livelink{chap:DWOPderef}{DW\-\_OP\-\_deref} operation pops the top stack entry and 
+The 
+\livelink{chap:DWOPderef}{DW\-\_OP\-\_deref} 
+operation 
+pops the top stack entry and 
 treats it as an address. The value
 retrieved from that address is pushed. 
-The size of the data retrieved from the dereferenced
+The size of the data retrieved from the 
+\addtoindexi{dereferenced}{address!dereference operator}
 address is the size of an address on the target machine.
 
 \item \livetarg{chap:DWOPderefsize}{DW\-\_OP\-\_deref\-\_size} \\
@@ -668,24 +678,30 @@ target machine before being pushed onto the expression stack.
 \item \livetarg{chap:DWOPxderef}{DW\-\_OP\-\_xderef} \\
 The \livelink{chap:DWOPxderef}{DW\-\_OP\-\_xderef} operation provides an extended dereference
 mechanism. The entry at the top of the stack is treated as an
-address. The second stack entry is treated as an “address
-space identifier” for those architectures that support
-multiple address spaces. The top two stack elements are popped,
+address. The second stack entry is treated as an ``address
+space identifier'' for those architectures that support
+\addtoindexi{multiple}{address space!multiple}
+address spaces. The top two stack elements are popped,
 and a data item is retrieved through an implementation\dash defined
 address calculation and pushed as the new stack top. The size
-of the data retrieved from the dereferenced address is the
+of the data retrieved from the 
+\addtoindexi{dereferenced}{address!dereference operator}
+address is the
 size of an address on the target machine.
 
 \item \livetarg{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size}\\
 The \livelink{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size} operation behaves like the
 \livelink{chap:DWOPxderef}{DW\-\_OP\-\_xderef} operation.The entry at the top of the stack is
 treated as an address. The second stack entry is treated as
-an “address space identifier” for those architectures
-that support multiple address spaces. The top two stack
+an ``address space identifier'' for those architectures
+that support 
+\addtoindexi{multiple}{address space!multiple}
+address spaces. The top two stack
 elements are popped, and a data item is retrieved through an
 implementation\dash defined address calculation and pushed as the
 new stack top. In the \livelink{chap:DWOPxderefsize}{DW\-\_OP\-\_xderef\-\_size} operation, however,
-the size in bytes of the data retrieved from the dereferenced
+the size in bytes of the data retrieved from the 
+\addtoindexi{dereferenced}{address!dereference operator}
 address is specified by the single operand. This operand is a
 1\dash byte unsigned integral constant whose value may not be larger
 than the size of an address on the target machine. The data
@@ -702,7 +718,9 @@ structure, or class whose address has been dynamically
 determined by an earlier step during user expression
 evaluation.  This operator provides explicit functionality
 (especially for arrays involving descriptors) that is analogous
-to the implicit push of the base address of a structure prior
+to the implicit push of the base 
+\addtoindexi{address}{address!implicit push of base}
+of a structure prior
 to evaluation of a \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} to access a
 data member of a structure. For an example, see 
 Appendix \refersec{app:aggregateexamples}.
@@ -1280,8 +1298,12 @@ attribute whose value is an offset from the beginning of
 the .debug\_loc section to the first byte of the list for the
 object in question.
 
-Each entry in a location list is either a location list entry,
-a base address selection entry, or an end of list entry.
+Each entry in a location list is either a location 
+\addtoindexi{list}{address selection|see{base address selection}} 
+entry,
+a 
+\addtoindexi{base}{base address selection entry!in location list} 
+address selection entry, or an end of list entry.
 
 A location list entry consists of:
 
@@ -1290,7 +1312,9 @@ A location list entry consists of:
 This address offset has the size of an address and is
 relative to the applicable base address of the compilation
 unit referencing this location list. It marks the beginning
-of the address range over which the location is valid.
+of the address 
+\addtoindexi{range}{address range!in location list} 
+over which the location is valid.
 
 \item An ending address offset.  This address offset again
 has the size of an address and is relative to the applicable
@@ -1325,7 +1349,10 @@ list do not collectively cover the entire range over which the
 object in question is defined, it is assumed that the object is
 not available for the portion of the range that is not covered.
 
-A base address selection entry consists of:
+A base 
+\addtoindexi{address}{address selection|see{base address selection}}
+selection 
+\addtoindexi{entry}{base address selection entry!in location list}:
 \begin{enumerate}[1]
 \item The value of the largest representable 
 address offset (for example, 0xffffffff when the size of
@@ -1477,7 +1504,10 @@ which is a \livelink{chap:flag}{flag}.
 \section{Segmented Addresses}
 \label{chap:segmentedaddresses}
 \textit{In some systems, addresses are specified as offsets within a
-given segment rather than as locations within a single flat
+given 
+\addtoindexx{address space!segmented}
+segment rather than as locations within a single flat
+\addtoindexx{address space!flat}.
 address space.}
 
 Any debugging information entry that contains a description
@@ -1501,16 +1531,23 @@ its containing compilation unit entry have \livelink{chap:DWATsegment}{DW\-\_AT\
 attributes, then the entry is assumed to exist within a flat
 address space. Similarly, if the entry has a \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
 attribute containing an empty location description, that
-entry is assumed to exist within a flat address space.
+entry is assumed to exist within a 
+\addtoindexi{flat}{address space!flat}.
+address space.
 
-\textit{Some systems support different classes of addresses. The
+\textit{Some systems support different classes of 
+addresses
+\addtoindexx{address class!attribute}. 
+The
 address class may affect the way a pointer is dereferenced
 or the way a subroutine is called.}
 
 
 Any debugging information entry representing a pointer or
-reference type or a subroutine or subroutine type may have
-a \livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class} attribute, whose value is an integer
+reference type or a subroutine or subroutine type may 
+have a 
+\livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
+attribute, whose value is an integer
 constant.  The set of permissible values is specific to
 each target architecture. The value \livetarg{chap:DWADDRnone}{DW\-\_ADDR\-\_none}, 
 however,
@@ -1758,7 +1795,9 @@ A range list entry consists of:
 \begin{enumerate}[1]
 \item A beginning address offset. This address offset has the size of an address and is relative to
 the applicable base address of the compilation unit referencing this range list. It marks the
-beginning of an address range.
+beginning of an 
+\addtoindexi{address}{address range!in range list} 
+range.
 
 \item An ending address offset. This address offset again has the size of an address and is relative
 to the applicable base address of the compilation unit referencing this range list. It marks the
index 70ac908..74c1a32 100644 (file)
@@ -1,4 +1,5 @@
 %DWARF5 local or useful Latex macros
+%Be sure to read the file READMEindexing.
 
 \dwf DWARF Debugging Information Format
 \docdate  % document date, like 1 April 1492
@@ -46,7 +47,9 @@ commands are allowed.
 % use like \refersec{chap:registerbasedaddressing}
 
 %Generate a live link into the doc
-% use like \livelink{DW\_OP\_dup}{chap:DWOPdup}
+% use like \livelink{chap:DWOPdup}{DW\_OP\_dup}
+%Generate a live link into the doc where the index entry != text
+% use like \livelinki{chap:DWATaddressclass}{address}{address class}
 
 % To print < use \textless and for > use \textgreater
 % which is awkward.
index 754d159..6126857 100644 (file)
@@ -145,7 +145,10 @@ compilation unit header referenced by the set.
 
 \item address\_size (ubyte) \\
 The size of an address in bytes on
-the target architecture. For segmented addressing, this is
+\addtoindexx{address\_size}
+the target architecture. For 
+\addtoindexx{address space!segmented}
+segmented addressing, this is
 the size of the offset portion of the address.
 
 \item segment\_size (ubyte) \\
@@ -273,7 +276,8 @@ compilation unit are assumed to be contiguous). \\
 \subsection{State Machine Registers}
 \label{chap:statemachineregisters}
 
-The line number information state machine has the following registers:
+The line number information state machine has the following 
+registers:
 \begin{longtable}{l|p{9cm}}
   \caption{State Machine Registers } \\
   \hline \\ \bfseries Register name&\bfseries Meaning\\ \hline
@@ -284,7 +288,7 @@ The line number information state machine has the following registers:
 \endfoot
   \hline
 \endlastfoot
-address &
+\addtoindexi{address}{address register!in line number machine}&
 The program\dash counter value corresponding to a machine instruction
 generated by the compiler. \\
 
@@ -1374,7 +1378,9 @@ any .debug\_info section, the augmentation string always uses
 UTF\dash 8 encoding.}
 
 \item  address\_size (ubyte) \\
-The size of a target address in this CIE and any FDEs that
+The size of a target address
+\addtoindexx{address\_size}
+in this CIE and any FDEs that
 use it, in bytes. If a compilation unit exists for this frame,
 its address size must match the address size here.
 
index 408f8ab..08f3495 100644 (file)
@@ -777,7 +777,11 @@ was used before the \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} was int
 Version 3). There is insufficient reason to change this.}
 
 
-Subroutines and entry points 
+Subroutines 
+and 
+entry
+\addtoindexx{address class!attribute}
+points 
 \hypertarget{chap:DWATaddressclasssubroutineorsubroutinetype}
 may also have 
 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} 
@@ -882,7 +886,9 @@ debuggers to support this same kind of referencing.}
 
 If 
 \hypertarget{chap:DWATstaticlinklocationofuplevelframe}
-a subroutine or entry point is nested, it may have a
+a 
+\addtoindexx{address!uplevel|see{static link attribute}}
+subroutine or entry point is nested, it may have a
 \livelink{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}
 attribute, whose value is a location
 description that computes the frame base of the relevant
index dd06efa..559ad98 100644 (file)
@@ -351,7 +351,10 @@ modifier.
 A modified type entry describing a pointer or reference
 type (using \livelink{chap:DWTAGpointertype}{DW\-\_TAG\-\_pointer\-\_type}, \livelink{chap:DWTAGreferencetype}{DW\-\_TAG\-\_reference\-\_type} or
 \livelink{chap:DWTAGrvaluereferencetype}{DW\-\_TAG\-\_rvalue\-\_reference\-\_type}) 
-may have 
+% Another instance of no-good-place-to-put-index entry.
+may
+\addtoindexx{address class!attribute} 
+have 
 \hypertarget{chap:DWATadressclasspointerorreferencetypes}
 a 
 \livelink{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
@@ -1662,10 +1665,16 @@ The \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} description is
 with the location descriptions for a particular object of the
 given pointer to member type and for a particular structure or
 class instance. The \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} attribute expects two
-values to be pushed onto the DWARF expression stack before
+values to be 
+\addtoindexi{pushed}{address!implicit push for member operator}
+onto the DWARF expression stack before
 the \livelink{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location} description is evaluated. The first
-value pushed is the value of the pointer to member object
-itself. The second value pushed is the base address of the
+value 
+\addtoindexi{pushed}{address!implicit push for member operator}
+is the value of the pointer to member object
+itself. The second value 
+\addtoindexi{pushed}{address!implicit push for member operator} 
+is the base address of the
 entire structure or union instance containing the member
 whose address is being calculated.