This is DW_AT_e* links implementation in the attributes table.
[dwarf-doc.git] / dwarf5 / latexdoc / generaldescription.tex
index 3839582..48b6697 100644 (file)
@@ -143,66 +143,66 @@ to one of the classes shown in Figure \refersec{tab:classesofattributevalue}.
   \hline
 \endlastfoot
 \livetarg{chap:DWATabstractorigin}{DW\-\_AT\-\_abstract\-\_origin}
-&Inline instances of inline subprograms \\
-&Out\dash{} of\dash{} line instances of inline subprograms \\
+&\livelink{chap:DWATabstractorigininlineinstance}{Inline instances of inline subprograms} \\
+% Heren livelink we cannot use \dash or \dash{}.
+&\livelink{chap:DWATabstractoriginoutoflineinstance}{Out-of-line instances of inline subprograms} \\
 \livetarg{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility}
-&C++ and Ada declarations \\
-&C++ base classes \\
-&C++ inherited members \\
+&\livelink{chap:DWATaccessibilitycandadadeclarations}{C++ and Ada declarations} \\
+&\livelink{chap:DWATaccessibilitycppbaseclasses}{C++ base classes} \\
+&\livelink{chap:DWATaccessibilitycppinheritedmembers}{C++ inherited members} \\
 \livetarg{chap:DWATaddressclass}{DW\-\_AT\-\_address\-\_class}
-&Pointer or reference types \\
-&Subroutine or subroutine type \\
+&\livelink{chap:DWATadressclasspointerorreferencetypes}{Pointer or reference types} \\
+&\livelink{chap:DWATaddressclasssubroutineorsubroutinetype}{Subroutine or subroutine type} \\
 \livetarg{chap:DWATallocated}{DW\-\_AT\-\_allocated}
-&Allocation status of types \\
+&\livelink{chap:DWATallocatedallocationstatusoftypes}{Allocation status of types} \\
 \livetarg{chap:DWATartificial}{DW\-\_AT\-\_artificial}
-&Objects or types that are not
-actually declared in the source \\
+&\livelink{chap:DWATartificialobjectsortypesthat}{Objects or types that are not
+actually declared in the source} \\
 \livetarg{chap:DWATassociated}{DW\-\_AT\-\_associated} 
-&Association status of types \\
+&\livelink{chap:DWATassociatedassociationstatusoftypes}{Association status of types} \\
 \livetarg{chap:DWATbasetypes}{DW\-\_AT\-\_base\-\_types} 
-&Primitive data types of compilation unit \\
+&\livelink{chap:DWATbasetypesprimitivedatatypesofcompilationunit}{Primitive data types of compilation unit} \\
 \livetarg{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} 
-&Binary scale factor for fixed\dash point type \\
+&\livelink{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}{Binary scale factor for fixed-point type} \\
 \livetarg{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} 
-&Base type bit location \\
-&Data member bit location \\
+&\livelink{chap:DWATbitoffsetbasetypebitlocation}{Base type bit location} \\
+&\livelink{chap:DWATbitoffsetdatamemberbitlocation}{Data member bit location} \\
 \livetarg{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} 
-&Base type bit size \\
-&Data member bit size \\
+&\livelink{chap:DWATbitsizebasetypebitsize}{Base type bit size} \\
+&\livelink{chap:DWATbitsizedatamemberbitsize}{Data member bit size} \\
 \livetarg{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} 
-&Array element stride (of array type) \\
-&Subrange stride (dimension of array type) \\
-&Enumeration stride (dimension of array type) \\
+&\livelink{chap:DWATbitstridearrayelementstrideofarraytype}{Array element stride (of array type)} \\
+&\livelink{chap:DWATbitstridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)} \\
+&\livelink{chap:DWATbitstrideenumerationstridedimensionofarraytype}{Enumeration stride (dimension of array type)} \\
 \livetarg{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} 
-&Data object or data type size \\
+&\livelink{chap:DWATbytesizedataobjectordatatypesize}{Data object or data type size} \\
 \livetarg{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} 
-&Array element stride (of array type) \\
-&Subrange stride (dimension of array type) \\
-&Enumeration stride (dimension of array type) \\
+&\livelink{chap:DWATbytestridearrayelementstrideofarraytype}{Array element stride (of array type)} \\
+&\livelink{chap:DWATbytestridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)} \\
+&\livelink{chap:DWATbytestrideenumerationstridedimensionofarraytype}{Enumeration stride (dimension of array type)} \\
 \livetarg{chap:DWATcallcolumn}{DW\-\_AT\-\_call\-\_column} 
-&Column position of inlined subroutine call \\
+&\livelink{chap:DWATcallcolumncolumnpositionofinlinedsubroutinecall}{Column position of inlined subroutine call}\\
 \livetarg{chap:DWATcallfile}{DW\-\_AT\-\_call\-\_file}
-&File containing inlined subroutine call \\
+&\livelink{chap:DWATcallfilefilecontaininginlinedsubroutinecall}{File containing inlined subroutine call} \\
 \livetarg{chap:DWATcallline}{DW\-\_AT\-\_call\-\_line} 
-&Line number of inlined subroutine call \\
+&\livelink{chap:DWATcalllinelinenumberofinlinedsubroutinecall}{Line number of inlined subroutine call} \\
 \livetarg{chap:DWATcallingconvention}{DW\-\_AT\-\_calling\-\_convention} 
-&Subprogram calling convention \\
-&\livetarg{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference} \\
-&Common \nolink{block} usage \\
+&\livelink{chap:DWATcallingconventionsubprogramcallingconvention}{Subprogram calling convention} \\
+\livetarg{chap:DWATcommonreference}{DW\-\_AT\-\_common\-\_reference}
+&\livelink{chap:commonreferencecommonblockusage}{Common block usage} \\
 \livetarg{chap:DWATcompdir}{DW\-\_AT\-\_comp\-\_dir}
-&Compilation directory \\
+&\livelink{chap:DWATcompdircompilationdirectory}{Compilation directory} \\
 \livetarg{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}
-&Constant object \\
-\livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value}
-&Enumeration literal value \\
-&Template value parameter \\
+&\livelink{chap:DWATconstvalueconstantobject}{Constant object} \\
+&\livelink{chap:DWATconstvalueenumerationliteralvalue}{Enumeration literal value} \\
+&\livelink{chap:DWATconstvaluetemplatevalueparameter}{Template value parameter} \\
 \livetarg{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr}
-&Compile\dash time constant object \\
-&Compile\dash time constant function \\
+&\livelink{chap:DWATconstexprcompiletimeconstantobject}{Compile-time constant object} \\
+&\livelink{chap:DWATconstexprcompiletimeconstantfunction}{Compile-time constant function} \\
 \livetarg{chap:DWATcontainingtype}{DW\-\_AT\-\_containing\-\_type}
-&Containing type of pointer to member type \\
+&\livelink{chap:DWATcontainingtypecontainingtypeofpointertomembertype}{Containing type of pointer to member type} \\
 \livetarg{chap:DWATcount}{DW\-\_AT\-\_count}
-&Elements of subrange type \\
+&\livelink{chap:DWATcountelementsofsubrangetype}{Elements of subrange type} \\
 \livetarg{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}
 &Base type bit location \\
 &Data member bit location \\
@@ -236,24 +236,24 @@ actually declared in the source \\
 \livetarg{chap:DWATdiscrvalue}{DW\-\_AT\-\_discr\-\_value}
 &Discriminant value\\
 \livetarg{chap:DWATelemental}{DW\-\_AT\-\_elemental}
-&Elemental property of a subroutine\\
+&\livelink{chap:DWATelementalelementalpropertyofasubroutine}{Elemental property of a subroutine} \\
 \livetarg{chap:DWATencoding}{DW\-\_AT\-\_encoding}
-&Encoding of base type\\
+&\livelink{chap:DWATencodingencodingofbasetype}{Encoding of base type} \\
 \livetarg{chap:DWATendianity}{DW\-\_AT\-\_endianity}
-&Endianity of data\\
+&\livelink{chap:DWATendianityendianityofdata}{Endianity of data} \\
 \livetarg{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}
-&Entry address of module initialization\\
-&Entry address of subprogram\\
-&Entry address of inlined subprogram\\
+&\livelink{chap:DWATentrypcentryaddressofmoduleinitialization}{Entry address of module initialization}\\
+&\livelink{chap:DWATentrypcentryaddressofsubprogram}{Entry address of subprogram} \\
+&\livelink{chap:DWATentrypcentryaddressofinlinedsubprogram}{Entry address of inlined subprogram}\\
 \livetarg{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}
-&Type safe enumeration definition\\
+&\livelink{chap:DWATenumclasstypesafeenumerationdefinition}{Type safe enumeration definition}\\
 \livetarg{chap:DWATexplicit}{DW\-\_AT\-\_explicit}
-&Explicit property of member function\\
+&\livelink{chap:DWATexplicitexplicitpropertyofmemberfunction}{Explicit property of member function}\\
 \livetarg{chap:DWATextension}{DW\-\_AT\-\_extension}
-&Previous namespace extension or original namespace\\
+&\livelink{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}{Previous namespace extension or original namespace}\\
 \livetarg{chap:DWATexternal}{DW\-\_AT\-\_external}
-&External subroutine\\
-&External variable\\
+&\livelink{chap:DWATexternalexternalsubroutine}{External subroutine} \\
+&\livelink{chap:DWATexternalexternalvariable}{External variable} \\
 \livetarg{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base}
 &Subroutine frame base address\\
 \livetarg{chap:DWATfriend}{DW\-\_AT\-\_friend}
@@ -349,7 +349,7 @@ corresponding to a declaration\\
 \livetarg{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8}
 &Compilation unit uses UTF\dash 8 strings \\
 \livetarg{chap:DWATvariableparameter}{DW\-\_AT\-\_variable\-\_parameter}
-&Non\dash constant parameter flag \\
+&Non\dash constant parameter \livelink{chap:flag}{flag} \\
 \livetarg{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality}
 &Virtuality indication \\
 &Virtuality of base class \\
@@ -434,7 +434,8 @@ of other debugging entries and by permitting the same debugging
 information entry to be one of many owned by another debugging
 information entry. 
 This makes it possible, for example, to
-describe the static \nolink{block} structure within a source file,
+describe the static \livelink{chap:lexicalblock}{block} structure 
+within a source file,
 to show the members of a structure, union, or class, and to
 associate declarations with source files or source files
 with shared objects.  
@@ -710,7 +711,8 @@ Appendix \refersec{app:aggregateexamples}.
 The \livelink{chap:DWOPformtlsaddress}{DW\-\_OP\-\_form\-\_tls\-\_address} operation pops a value from the
 stack, translates it into an address in the current thread's
 thread\dash local storage \nolink{block}, and pushes the address. If the
-DWARF expression containing the \livelink{chap:DWOPformtlsaddress}{DW\-\_OP\-\_form\-\_tls\-\_address}
+DWARF expression containing 
+the \livelink{chap:DWOPformtlsaddress}{DW\-\_OP\-\_form\-\_tls\-\_address}
 operation belongs to the main executable's DWARF info, the
 operation uses the main executable's thread\dash local storage
 \nolink{block}; if the expression belongs to a shared library's
@@ -982,7 +984,8 @@ and/or other
 DWARF operations specific to describing locations. They are
 sufficient for describing the location of any object as long
 as its lifetime is either static or the same as the lexical
-\nolink{block} that owns it, and it does not move during its lifetime.
+\livelink{chap:lexicalblock}{block} that owns it, 
+and it does not move during its lifetime.
 
 Single location descriptions are of two kinds:
 \begin{enumerate}[a]
@@ -1108,6 +1111,7 @@ or is computed from other locations and values in the program.
 \item \livetarg{chap:DWOPimplicitvalue}{DW\-\_OP\-\_implicit\-\_value} \\
 The \livelink{chap:DWOPimplicitvalue}{DW\-\_OP\-\_implicit\-\_value} operation specifies an immediate value
 using two operands: an unsigned LEB128 length, followed by
+%FIXME: should this block be a reference? To what?
 a \nolink{block} representing the value in the memory representation
 of the target machine. The length operand gives the length
 in bytes of the \nolink{block}.
@@ -1383,7 +1387,10 @@ the accessibility of an object or of some other program
 entity. The accessibility specifies which classes of other
 program objects are permitted access to the object in question.}
 
-The accessibility of a declaration is represented by a \livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} attribute, whose
+The accessibility of a declaration is 
+\hypertarget{chap:DWATaccessibilitycandadadeclarations}
+represented by a 
+\livelink{chap:DWATaccessibility}{DW\-\_AT\-\_accessibility} attribute, whose
 value is a constant drawn from the set of codes listed in Figure 
 \ref{fig:accessibilitycodes}.
 
@@ -1456,7 +1463,10 @@ functions.}
 Any debugging information entry representing the
 declaration of an object or type artificially generated by
 a compiler and not explicitly declared by the source program
-may have a \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute, which is a \livelink{chap:flag}{flag}.
+\hypertarget{chap:DWATartificialobjectsortypesthat}
+may have a 
+\livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute, 
+which is a \livelink{chap:flag}{flag}.
 
 \section{Segmented Addresses}
 \label{chap:segmentedaddresses}
@@ -1595,7 +1605,7 @@ multiple whitespace characters may be compressed.}
 
 \section{Data Locations and DWARF Procedures}
 Any debugging information entry describing a data object (which
-includes variables and parameters) or common \nolink{block} may have a
+includes variables and parameters) or common \livelink{chap:commonblockentry}{block} may have a
 \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute, whose value is a location description
 (see Section 2.6).  
 
@@ -1619,7 +1629,9 @@ DWARF expression operator
 Any debugging information entry describing an entity that has
 a machine code address or range of machine code addresses,
 which includes compilation units, module initialization,
-subroutines, ordinary \nolink{block}, try/catch \nolink{blocks}, labels and
+subroutines, ordinary \livelink{chap:lexicalblock}{block}, 
+try/catch \nolink{blocks} (see Section\refersec{chap:tryandcatchblockentries}), 
+labels and
 the like, may have
 
 \begin{itemize}
@@ -1751,8 +1763,11 @@ cases, the entry address needs to be specified explicitly.}
 
 Any debugging information entry describing an entity that has
 a range of code addresses, which includes compilation units,
-module initialization, subroutines, ordinary \nolink{block}, try/catch
-\nolink{blocks}, and the like, may have a \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute to
+module initialization, subroutines, 
+ordinary \livelink{chap:lexicalblock}{block}, 
+try/catch \nolink{blocks} (see Section \refersec{chap:tryandcatchblockentries}),
+and the like, 
+may have a \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute to
 indicate the first executable instruction within that range
 of addresses. The value of the \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute is a
 relocated address. If no \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute is present,