DW_AT_t* through DW_AT_v* attributes table entries done.
[dwarf-doc.git] / dwarf5 / latexdoc / generaldescription.tex
index 2093995..f84c3f7 100644 (file)
@@ -255,34 +255,34 @@ actually declared in the source} \\
 &\livelink{chap:DWATexternalexternalsubroutine}{External subroutine} \\
 &\livelink{chap:DWATexternalexternalvariable}{External variable} \\
 \livetarg{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base}
-&Subroutine frame base address\\
+&\livelink{chap:DWATframebasesubroutineframebaseaddress}{Subroutine frame base address} \\
 \livetarg{chap:DWATfriend}{DW\-\_AT\-\_friend}
-&Friend relationship\\
+&\livelink{chap:DWATfriendfriendrelationship}{Friend relationship} \\
 \livetarg{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}
-&Contiguous range of code addresses\\
+&\livelink{chap:DWAThighpccontinguousrangeofcodeaddresses}{Contiguous range of code addresses} \\
 \livetarg{chap:DWATidentifiercase}{DW\-\_AT\-\_identifier\-\_case}
-&Identifier case rule \\
+&\livelink{chap:DWATidentifiercaseidentifiercaserule}{Identifier case rule} \\
 \livetarg{chap:DWATimport}{DW\-\_AT\-\_import}
-&Imported declaration \\
-&Imported unit \\
-&Namespace alias \\
-&Namespace using declaration \\
-&Namespace using directive \\
+&\livelink{chap:DWATimportimporteddeclaration}{Imported declaration} \\
+&\livelink{chap:DWATimportimportedunit}{Imported unit} \\
+&\livelink{chap:DWATimportnamespacealias}{Namespace alias} \\
+&\livelink{chap:DWATimportnamespaceusingdeclaration}{Namespace using declaration} \\
+&\livelink{chap:DWATimportnamespaceusingdirective}{Namespace using directive} \\
 \livetarg{chap:DWATinline}{DW\-\_AT\-\_inline}
-&Abstract instance\\
-&Inlined subroutine\\
+&\livelink{chap:DWATinlineabstracttinstance}{Abstract instance} \\
+&\livelink{chap:DWATinlineinlinedsubroutine}{Inlined subroutine} \\
 \livetarg{chap:DWATisoptional}{DW\-\_AT\-\_is\-\_optional}
-&Optional parameter\\
+&\livelink{chap:DWATisoptionaloptionalparameter}{Optional parameter} \\
 \livetarg{chap:DWATlanguage}{DW\-\_AT\-\_language}
-&Programming language\\
+&\livelink{chap:DWATlanguageprogramminglanguage}{Programming language} \\
 \livetarg{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name}
-&Object file linkage name of an entity\\
+&\livelink{chap:DWATlinkagenameobjectfilelinkagenameofanentity}{Object file linkage name of an entity}\\
 \livetarg{chap:DWATlocation}{DW\-\_AT\-\_location}
-&Data object location\\
+&\livelink{chap:DWATlocationdataobjectlocation}{Data object location}\\
 \livetarg{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}
-&Code address or range of addresses\\
+&\livelink{chap:DWATlowpccodeaddressorrangeofaddresses}{Code address or range of addresses}\\
 \livetarg{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}
-&Lower bound of subrange\\
+&\livelink{chap:DWATlowerboundlowerboundofsubrange}{Lower bound of subrange} \\
 \livetarg{chap:DWATmacroinfo}{DW\-\_AT\-\_macro\-\_info}
 &\livelink{chap:DWATmacroinfomacroinformation}{Macro information} (\#define, \#undef)\\
 \livetarg{chap:DWATmainsubprogram}{DW\-\_AT\-\_main\-\_subprogram}
@@ -300,64 +300,63 @@ actually declared in the source} \\
 \livetarg{chap:DWATordering}{DW\-\_AT\-\_ordering}
 &\livelink{chap:DWATorderingarrayrowcolumnordering}{Array row/column ordering} \\
 \livetarg{chap:DWATpicturestring}{DW\-\_AT\-\_picture\-\_string}
-&Picture string for numeric string type\\
+&\livelink{chap:DWATpicturestringpicturestringfornumericstringtype}{Picture string for numeric string type} \\
 \livetarg{chap:DWATpriority}{DW\-\_AT\-\_priority}
-&Module priority\\
+&\livelink{chap:DWATprioritymodulepriority}{Module priority}\\
 \livetarg{chap:DWATproducer}{DW\-\_AT\-\_producer}
-&Compiler identification\\
+&\livelink{chap:DWATproducercompileridentification}{Compiler identification}\\
 \livetarg{chap:DWATprototyped}{DW\-\_AT\-\_prototyped}
-&Subroutine prototype\\
+&\livelink{chap:DWATprototypedsubroutineprototype}{Subroutine prototype}\\
 \livetarg{chap:DWATpure}{DW\-\_AT\-\_pure}
-&Pure property of a subroutine\\
+&\livelink{chap:DWATpurepurepropertyofasubroutine}{Pure property of a subroutine} \\
 \livetarg{chap:DWATranges}{DW\-\_AT\-\_ranges}
-&Non\dash contiguous range of code addresses\\
+&\livelink{chap:DWATrangesnoncontiguousrangeofcodeaddresses}{Non-contiguous range of code addresses} \\
 \livetarg{chap:DWATrecursive}{DW\-\_AT\-\_recursive}
-&Recursive property of a subroutine\\
+&\livelink{chap:DWATrecursiverecursivepropertyofasubroutine}{Recursive property of a subroutine} \\
 \livetarg{chap:DWATreturnaddr}{DW\-\_AT\-\_return\-\_addr}
-&Subroutine return address save location\\
+&\livelink{chap:DWATreturnaddrsubroutinereturnaddresssavelocation}{Subroutine return address save location} \\
 \livetarg{chap:DWATsegment}{DW\-\_AT\-\_segment}
-&Addressing information\\
+&\livelink{chap:DWATsegmentaddressinginformation}{Addressing information} \\
 \livetarg{chap:DWATsibling}{DW\-\_AT\-\_sibling}
-&Debugging information entry relationship\\
+&\livelink{chap:DWATsiblingdebugginginformationentryrelationship}{Debugging information entry relationship} \\
 \livetarg{chap:DWATsmall}{DW\-\_AT\-\_small}
-&Scale factor for fixed\dash point type\\
+&\livelink{chap:DWATsmallscalefactorforfixedpointtype}{Scale factor for fixed-point type} \\
 \livetarg{chap:DWATsignature}{DW\-\_AT\-\_signature}
-&Type signature\\
+&\livelink{chap:DWATsignaturetypesignature}{Type signature}\\
 \livetarg{chap:DWATspecification}{DW\-\_AT\-\_specification}
-&Incomplete, non\dash defining, or separate declaration
-corresponding to a declaration\\
+&\livelink{chap:DWATspecificationincompletenondefiningorseparatedeclaration}{Incomplete, non-defining, or separate declaration corresponding to a declaration } \\
 \livetarg{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope}
-&Object declaration\\
-&Type declaration\\
+&\livelink{chap:DWATstartscopeobjectdeclaration}{Object declaration}\\
+&\livelink{chap:DWATstartscopetypedeclaration}{Type declaration}\\
 \livetarg{chap:DWATstaticlink}{DW\-\_AT\-\_static\-\_link}
-&Location of uplevel frame\\
+&\livelink{chap:DWATstaticlinklocationofuplevelframe}{Location of uplevel frame} \\
 \livetarg{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list}
-&Line number information for unit\\
+&\livelink{chap:DWATstmtlistlinenumberinformationforunit}{Line number information for unit}\\
 \livetarg{chap:DWATstringlength}{DW\-\_AT\-\_string\-\_length}
-&String length of string type\\
+&\livelink{chap:DWATstringlengthstringlengthofstringtype}{String length of string type} \\
 \livetarg{chap:DWATthreadsscaled}{DW\-\_AT\-\_threads\-\_scaled}
-&UPC array bound THREADS scale factor\\
+&\livelink{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}{UPC array bound THREADS scale factor}\\
 \livetarg{chap:DWATtrampoline}{DW\-\_AT\-\_trampoline}
-&Target subroutine\\
+&\livelink{chap:DWATtrampolinetargetsubroutine}{Target subroutine} \\
 \livetarg{chap:DWATtype}{DW\-\_AT\-\_type}
-&Type of declaration\\
-&Type of subroutine return\\
+&\livelink{chap:DWATtypetypeofdeclaration}{Type of declaration} \\
+&\livelink{chap:DWATtypetypeofsubroutinereturn}{Type of subroutine return} \\
 \livetarg{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}
-&Upper bound of subrange\\
+&\livelink{chap:DWATupperboundupperboundofsubrange}{Upper bound of subrange} \\
 \livetarg{chap:DWATuselocation}{DW\-\_AT\-\_use\-\_location}
-&Member location for pointer to member type\\
+&\livelink{chap:DWATuselocationmemberlocationforpointertomembertype}{Member location for pointer to member type} \\
 \livetarg{chap:DWATuseUTF8}{DW\-\_AT\-\_use\-\_UTF8}
-&Compilation unit uses UTF\dash 8 strings \\
+&\livelink{chap:DWATuseUTF8compilationunitusesutf8strings}{Compilation unit uses UTF-8 strings} \\
 \livetarg{chap:DWATvariableparameter}{DW\-\_AT\-\_variable\-\_parameter}
-&Non\dash constant parameter \livelink{chap:flag}{flag} \\
+&\livelink{chap:DWATvariableparameternonconstantparameterflag}{Non-constant parameter flag}  \\
 \livetarg{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality}
-&Virtuality indication \\
-&Virtuality of base class \\
-&Virtuality of function \\
+&\livelink{chap:DWATvirtualityvirtualityindication}{Virtuality indication} \\
+&\livelink{chap:DWATvirtualityvirtualityofbaseclass}{Virtuality of base class} \\
+&\livelink{chap:DWATvirtualityvirtualityoffunction}{Virtuality of function} \\
 \livetarg{chap:DWATvisibility}{DW\-\_AT\-\_visibility}
-&Visibility of declaration\\
+&\livelink{chap:DWATvisibilityvisibilityofdeclaration}{Visibility of declaration} \\
 \livetarg{chap:DWATvtableelemlocation}{DW\-\_AT\-\_vtable\-\_elem\-\_location}
-&Virtual function vtable slot\\
+&\livelink{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}{Virtual function vtable slot}\\
 \end{longtable}
 
 \begin{figure}[here]
@@ -477,6 +476,7 @@ children are represented as siblings of the first child.
 A chain of sibling entries is terminated by a null entry.
 
 In cases where a producer of debugging information feels that
+\hypertarget{chap:DWATsiblingdebugginginformationentryrelationship}
 it will be important for consumers of that information to
 quickly scan chains of sibling entries, while ignoring the
 children of individual siblings, that producer may attach a
@@ -1363,7 +1363,9 @@ and representation.}
 
 \section{Types of Program Entities}
 \label{chap:typesofprogramentities}
-Any debugging information entry describing a declaration that
+Any 
+\hypertarget{chap:DWATtypetypeofdeclaration}
+debugging information entry describing a declaration that
 has a type has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute, whose value is a
 reference to another debugging information entry. The entry
 referenced may describe a base type, that is, a type that is
@@ -1414,7 +1416,9 @@ visibility specifies which declarations are to be
 visible outside of the entity in which they are
 declared.}
 
-The visibility of a declaration is represented 
+The 
+\hypertarget{chap:DWATvisibilityvisibilityofdeclaration}
+visibility of a declaration is represented 
 by a \livelink{chap:DWATvisibility}{DW\-\_AT\-\_visibility} attribute, whose value is a
 constant drawn from the set of codes listed in 
 Figure \ref{fig:visibilitycodes}.
@@ -1435,7 +1439,9 @@ Figure \ref{fig:visibilitycodes}.
 \textit{C++ provides for virtual and pure virtual structure or class
 member functions and for virtual base classes.}
 
-The virtuality of a declaration is represented by a
+The 
+\hypertarget{chap:DWATvirtualityvirtualityindication}
+virtuality of a declaration is represented by a
 \livelink{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality} attribute, whose value is a constant drawn
 from the set of codes listed in 
 Figure \ref{fig:virtualitycodes}.
@@ -1475,8 +1481,11 @@ given segment rather than as locations within a single flat
 address space.}
 
 Any debugging information entry that contains a description
+\hypertarget{chap:DWATsegmentaddressinginformation}
 of the location of an object or subroutine may have
-a \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, whose value is a location
+a 
+\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
+attribute, whose value is a location
 description. The description evaluates to the segment selector
 of the item being described. If the entry containing the
 \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute has a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc}, \livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc},
@@ -1554,6 +1563,37 @@ void myfunc()
 value of the variable x passed to the function g is the value of the
 global variable x rather than of the local version.}
 
+\subsection{Non-Defining Declarations}
+A debugging information entry that represents a non-defining or otherwise incomplete
+declaration of a program entity has a 
+\livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} 
+attribute, which is a 
+\livelink{chap:flag}{flag}.
+
+\subsection{Declarations Completing Non-Defining Declarations}
+A debugging information entry that represents a 
+\hypertarget{chap:DWATspecificationincompletenondefiningorseparatedeclaration}
+declaration that completes another (earlier) 
+non\dash defining declaration may have a 
+\livelink{chap:DWATspecification}{DW\-\_AT\-\_specification}
+attribute whose value is a reference to
+the debugging information entry representing the non-defining declaration. A debugging
+information entry with a 
+\livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} 
+attribute does not need to duplicate information
+provided by the debugging information entry referenced by that specification attribute.
+
+It is not the case that all attributes of the debugging information entry referenced by a
+\livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute 
+apply to the referring debugging information entry.
+
+\textit{For example,
+\livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} and 
+\livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} 
+clearly cannot apply to a referring
+entry.}
+
+
 
 \section{Declaration Coordinates}
 \label{chap:declarationcoordinates}
@@ -1615,7 +1655,10 @@ 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 \livelink{chap:commonblockentry}{block} may have a
+\hypertarget{chap:DWATlocationdataobjectlocation}
+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).  
 
@@ -1639,9 +1682,13 @@ 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,
+\hypertarget{chap:DWATrangesnoncontiguousrangeofcodeaddresses}
 subroutines, ordinary \livelink{chap:lexicalblock}{block}, 
 try/catch \nolink{blocks} (see Section\refersec{chap:tryandcatchblockentries}), 
-labels and
+labels 
+\hypertarget{chap:DWATlowpccodeaddressorrangeofaddresses}
+and
+\hypertarget{chap:DWAThighpccontinguousrangeofcodeaddresses}
 the like, may have
 
 \begin{itemize}
@@ -1883,12 +1930,15 @@ associated distinct linkage name it may sometimes be useful
 for a producer to include this name in the DWARF description
 of the program to facilitate consumer access to and use of
 object file information about an entity and/or information
+\hypertarget{chap:DWATlinkagenameobjectfilelinkagenameofanentity}
 that is encoded in the linkage name itself.  
 }
 
 % Some trouble maybe with hbox full, so we try optional word breaks.
 A debugging
-information entry may have a \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute
+information entry may have a 
+\livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name}
+attribute
 whose value is a null-terminated string describing the object
 file linkage name associated with the corresponding entity.