Signed-off-by: Ron Brender <ron.brender@gmail.com>
[dwarf-doc.git] / dwarf5 / latexdoc / typeentries.tex
index 55f51a5..7e0d371 100644 (file)
@@ -5,7 +5,7 @@ that describe program types: base types, modified types and
 user\dash defined types.
 
 If the scope of the declaration of a named type begins after
-\hypertarget{chap:DWATstartscopetypedeclaration}
+\hypertarget{chap:DWATstartscopetypedeclaration}{}
 the low pc value for the scope most closely enclosing the
 declaration, the declaration may have a 
 \DWATstartscope{}
@@ -55,9 +55,9 @@ If omitted, the encoding assumes the representation that
 is the default for the target architecture.
 
 A base type entry has 
-\hypertarget{chap:DWATbytesizedataobjectordatatypesize}
+\hypertarget{chap:DWATbytesizedataobjectordatatypesize}{}
 either a \DWATbytesize{} attribute
-\hypertarget{chap:DWATbitsizebasetypebitsize}
+\hypertarget{chap:DWATbitsizebasetypebitsize}{}
 or a \DWATbitsize{} attribute 
 \addtoindexx{bit size attribute}
 whose \livelink{chap:classconstant}{integer constant} value
@@ -75,7 +75,7 @@ and a byte size attribute whose value is 4.}
 
 If the value of an object of the given type does not fully
 occupy the storage described by a byte size attribute,
-\hypertarget{chap:DWATdatabitoffsetbasetypebitlocation}
+\hypertarget{chap:DWATdatabitoffsetbasetypebitlocation}{}
 the base type entry may also have 
 \addtoindexx{bit size attribute}
 a 
@@ -109,7 +109,7 @@ in
 is also used for bit field members 
 (see Section \refersec{chap:datamemberentries}). 
 It
-\hypertarget{chap:DWATbitoffsetbasetypebitlocation}
+\hypertarget{chap:DWATbitoffsetbasetypebitlocation}{}
 replaces the attribute 
 \DWATbitoffset{} 
 when used for base
@@ -178,9 +178,9 @@ signed
 or 
 \addtoindexx{digit count attribute}
 unsigned. 
-\hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}
+\hypertarget{chap:DWATdecimalsigndecimalsignrepresentation}{}
 These 
-\hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}
+\hypertarget{chap:DWATdigitcountdigitcountforpackeddecimalornumericstringtype}{}
 base types are used in combination with
 \DWATdecimalsign, 
 \DWATdigitcount{} and 
@@ -232,7 +232,7 @@ is an \livelink{chap:classconstant}{integer constant}
 value that represents the number of digits in an instance of
 the type.
 
-\hypertarget{chap:DWATdecimalscaledecimalscalefactor}
+\hypertarget{chap:DWATdecimalscaledecimalscalefactor}{}
 The \DWATdecimalscale{}
 attribute 
 \addtoindexx{decimal scale attribute}
@@ -249,7 +249,7 @@ digits on the left are not stored in an instance of the type.
 
 The \DWATEedited{}
 base 
-\hypertarget{chap:DWATpicturestringpicturestringfornumericstringtype}
+\hypertarget{chap:DWATpicturestringpicturestringfornumericstringtype}{}
 type is used to represent an edited
 numeric or alphanumeric data type. It is used in combination
 with a \DWATpicturestring{} attribute whose value is a 
@@ -298,7 +298,7 @@ interpretation as described for the
 \DWATEpackeddecimal{}
 and \DWATEnumericstring{} base types.
 
-\hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}
+\hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}{}
 For a data type with a binary scale factor, the fixed
 \addtoindexx{binary scale attribute}
 binary type entry has a 
@@ -317,7 +317,7 @@ larger than the number of bits, this implies additional zero
 bits on the left are not stored in an instance of the type.
 
 For 
-\hypertarget{chap:DWATsmallscalefactorforfixedpointtype}
+\hypertarget{chap:DWATsmallscalefactorforfixedpointtype}{}
 a data type with a non\dash decimal and non\dash binary scale factor,
 the fixed binary type entry has a 
 \DWATsmall{} attribute which
@@ -413,7 +413,7 @@ pointer or \addtoindex{reference type}
 may
 \addtoindexx{address class!attribute} 
 have 
-\hypertarget{chap:DWATadressclasspointerorreferencetypes}
+\hypertarget{chap:DWATadressclasspointerorreferencetypes}{}
 a 
 \DWATaddressclass{}
 attribute to describe how objects having the given pointer
@@ -579,7 +579,7 @@ null\dash terminated string containing the array type name as it
 appears in the source program.
 
 The 
-\hypertarget{chap:DWATorderingarrayrowcolumnordering}
+\hypertarget{chap:DWATorderingarrayrowcolumnordering}{}
 array type entry describing a multidimensional array may
 \addtoindexx{array!element ordering}
 have a \DWATordering{} attribute whose 
@@ -615,9 +615,9 @@ If the amount of storage allocated to hold each element of an
 object of the given array type is different from the amount
 \addtoindexx{stride attribute|see{bit stride attribute or byte stride attribute}}
 of storage that is normally allocated to hold an individual
-\hypertarget{chap:DWATbitstridearrayelementstrideofarraytype}
+\hypertarget{chap:DWATbitstridearrayelementstrideofarraytype}{}
 object of the 
-\hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}
+\hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}{}
 indicated element type, then the array type
 \addtoindexx{bit stride attribute}
 entry has either a 
@@ -790,7 +790,7 @@ in the source program.
 A structure type, union type or class type entry may have
 either a \DWATbytesize{} or a
 \DWATbitsize{} attribute 
-\hypertarget{chap:DWATbitsizedatamemberbitsize}
+\hypertarget{chap:DWATbitsizedatamemberbitsize}{}
 (see Section \refersec{chap:byteandbitsizes}), 
 whose value is the amount of storage needed
 to hold an instance of the structure, union or class type,
@@ -806,7 +806,7 @@ entry that does not have a byte size attribute and that has
 a \DWATdeclaration{} attribute.
 
 If the complete declaration of a type has been placed in
-\hypertarget{chap:DWATsignaturetypesignature}
+\hypertarget{chap:DWATsignaturetypesignature}{}
 a separate \addtoindex{type unit}
 (see Section \refersec{chap:separatetypeunitentries}), 
 an incomplete declaration 
@@ -950,7 +950,7 @@ of the inheritance entry is derived, extended or implementing.
 An inheritance entry 
 \addtoindexx{inheritance entry}
 for a class that derives from or extends
-\hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}
+\hypertarget{chap:DWATdatamemberlocationinheritedmemberlocation}{}
 another class or struct also has 
 \addtoindexx{data member location attribute}
 a 
@@ -974,7 +974,7 @@ members
 An 
 \addtoindexx{inheritance entry}
 inheritance entry 
-\hypertarget{chap:DWATaccessibilitycppinheritedmembers}
+\hypertarget{chap:DWATaccessibilitycppinheritedmembers}{}
 may 
 \addtoindexx{accessibility attribute}
 have a
@@ -986,7 +986,7 @@ and public access is assumed for an entry of an interface,
 struct or union.
 
 If 
-\hypertarget{chap:DWATvirtualityvirtualityofbaseclass}
+\hypertarget{chap:DWATvirtualityvirtualityofbaseclass}{}
 the class referenced by the 
 \addtoindexx{inheritance entry}
 inheritance entry serves
@@ -1024,7 +1024,7 @@ in the declaration in the source program, including any class
 or structure qualifiers.
 
 An access declaration entry 
-\hypertarget{chap:DWATaccessibilitycppbaseclasses}
+\hypertarget{chap:DWATaccessibilitycppbaseclasses}{}
 also 
 has a 
 \DWATaccessibility{}
@@ -1039,7 +1039,7 @@ entities.
 Each \doublequote{friend} 
 \addtoindexx{friend entry}
 declared by a structure, union or class
-\hypertarget{chap:DWATfriendfriendrelationship}
+\hypertarget{chap:DWATfriendfriendrelationship}{}
 type may be represented by a debugging information entry
 that is a child of the structure, union or class type entry;
 the friend entry has the 
@@ -1086,7 +1086,7 @@ access is assumed for an entry of a class and public access
 is assumed for an entry of a structure, union, or interface.
 
 A data member 
-\hypertarget{chap:DWATmutablemutablepropertyofmemberdata}
+\hypertarget{chap:DWATmutablemutablepropertyofmemberdata}{}
 entry 
 \addtoindexx{member entry (data)}
 may 
@@ -1114,9 +1114,9 @@ the target system.
 The member entry 
 \addtoindexx{member entry (data)}
 corresponding to a data member that is
-\hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}
+\hypertarget{chap:DWATdatabitoffsetdatamemberbitlocation}{}
 defined 
-\hypertarget{chap:DWATdatamemberlocationdatamemberlocation}
+\hypertarget{chap:DWATdatamemberlocationdatamemberlocation}{}
 in a structure, union or class may have either
 \addtoindexx{data member location attribute}
 a
@@ -1332,6 +1332,12 @@ may contain the same attributes and follows the same rules
 as non\dash member global subroutine entries 
 (see Section \refersec{chap:subroutineandentrypointentries}).
 
+\textit{In particular, if the member function entry is an
+instantiation of a member function template, it follows the 
+same rules as function template instantiations (see Section 
+\refersec{chap:functiontemplateinstantiations}).
+}
+
 A 
 \addtoindexx{accessibility attribute}
 member function entry may have a 
@@ -1341,13 +1347,13 @@ access is assumed for an entry of a class and public access
 is assumed for an entry of a structure, union or interface.
 
 If 
-\hypertarget{chap:DWATvirtualityvirtualityoffunction}
+\hypertarget{chap:DWATvirtualityvirtualityoffunction}{}
 the member function entry describes a virtual function,
 then that entry has a 
 \DWATvirtuality{} attribute.
 
 If 
-\hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}
+\hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}{}
 the member function entry describes an explicit member
 function, then that entry has 
 \addtoindexx{explicit attribute}
@@ -1355,7 +1361,7 @@ a
 \DWATexplicit{} attribute.
 
 An 
-\hypertarget{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}
+\hypertarget{chap:DWATvtableelemlocationvirtualfunctiontablevtableslot}{}
 entry for a virtual function also has a
 \DWATvtableelemlocation{}
 \addtoindexi{attribute}{vtable element location attribute} whose value contains
@@ -1367,7 +1373,7 @@ type is pushed onto the expression stack before the location
 description is evaluated.
 
 If 
-\hypertarget{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}
+\hypertarget{chap:DWATobjectpointerobjectthisselfpointerofmemberfunction}{}
 the member function entry describes a non\dash static member
 \addtoindexx{this pointer attribute|see{object pointer attribute}}
 function, then that entry 
@@ -1425,73 +1431,24 @@ whose definition they represent.
 
 \textit{In \addtoindex{C++} a class template is a generic definition of a class
 type that may be instantiated when an instance of the class
-is declared or defined. The generic description of the
-class may include both parameterized types and parameterized
-constant values. DWARF does not represent the generic template
+is declared or defined. The generic description of the class may include
+parameterized types, parameterized compile-time constant
+values, and/or parameterized run-time constant addresses. 
+DWARF does not represent the generic template
 definition, but does represent each instantiation.}
 
 A class template instantiation is represented by a
 debugging information entry with the tag \DWTAGclasstype,
 \DWTAGstructuretype{} or 
-\DWTAGuniontype. With five
+\DWTAGuniontype. With the following
 exceptions, such an entry will contain the same attributes
 and have the same types of child entries as would an entry
 for a class type defined explicitly using the instantiation
 types and values. The exceptions are:
 
 \begin{enumerate}[1. ]
-\item Each formal parameterized type declaration appearing in the
-template definition is represented by a debugging information
-entry with the tag 
-\DWTAGtemplatetypeparameter. Each
-such entry may have a \DWATname{} attribute,
-\addtoindexx{name attribute}
-whose value is
-a null\dash terminated string containing the name of the formal
-type parameter as it appears in the source program. The
-template type parameter entry also has 
-\addtoindexx{type attribute}
-a 
-\DWATtype{} attribute
-describing the actual type by which the formal is replaced
-for this instantiation.
-
-\item Each formal parameterized value declaration appearing in the
-template definition is represented by a 
-debugging information entry with the 
-\addtoindexx{template value parameter entry}
-tag \DWTAGtemplatevalueparameterTARG. 
-Each
-such entry may have a 
-\DWATname{} attribute,
-\addtoindexx{name attribute}
-whose value is
-a null\dash terminated string containing the name of the formal
-value parameter as it appears in the source program. 
-The
-\hypertarget{chap:DWATconstvaluetemplatevalueparameter}
-template value parameter entry 
-\addtoindexx{template value parameter entry}
-also has 
-\addtoindexx{type attribute}
-a 
-\DWATtype{} attribute
-describing the type of the parameterized value. Finally,
-the template value parameter entry has a 
-\DWATconstvalue{}
-attribute, whose value is the actual constant value of the
-value parameter for this instantiation as represented on the
-target architecture.
-
-\needlines{5}
-\item The class type entry and each of its child entries reference
-a \addtoindex{template type parameter entry} in any circumstance where the
-source template definition references a formal parameterized
-type. 
-Similarly, the class type entry and each of its child
-entries reference a template value parameter entry in any
-circumstance where the source template definition references
-a formal parameterized value.
+\item Template parameters are described and referenced as
+specified in Section \refersec{chap:templateparameters}.
 
 \needlines{4}
 \item If the compiler has generated a special compilation unit to
@@ -1521,7 +1478,7 @@ tag \DWTAGvariantpartTARG{} and is
 owned by the corresponding structure type entry.
 
 If the variant part has a discriminant, the discriminant is
-\hypertarget{chap:DWATdiscrdiscriminantofvariantpart}
+\hypertarget{chap:DWATdiscrdiscriminantofvariantpart}{}
 represented by a 
 \addtoindexx{discriminant (entry)}
 separate debugging information entry which
@@ -1543,7 +1500,7 @@ a
 the tag type.
 
 Each variant of a particular variant part is represented by
-\hypertarget{chap:DWATdiscrvaluediscriminantvalue}
+\hypertarget{chap:DWATdiscrvaluediscriminantvalue}{}
 a debugging information entry\addtoindexx{variant entry} with the 
 tag \DWTAGvariantTARG{}
 and is a child of the variant part entry. The value that
@@ -1558,7 +1515,7 @@ an unsigned type.
 
 \needlines{5}
 Alternatively, 
-\hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}
+\hypertarget{chap:DWATdiscrlistlistofdiscriminantvalues}{}
 the variant entry may contain 
 \addtoindexx{discriminant list attribute}
 a 
@@ -1706,7 +1663,7 @@ required.
 \textit{In \addtoindex{C} or \addtoindex{C++}, 
 the underlying type will be the appropriate
 integral type determined by the compiler from the properties of
-\hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}
+\hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}{}
 the enumeration literal values. 
 A \addtoindex{C++} type declaration written
 using enum class declares a strongly typed enumeration and
@@ -1727,7 +1684,7 @@ Each \addtoindex{enumerator entry} has a
 \DWATname{} attribute, whose
 \addtoindexx{name attribute}
 value is a null\dash terminated string containing the name of the
-\hypertarget{chap:DWATconstvalueenumerationliteralvalue}
+\hypertarget{chap:DWATconstvalueenumerationliteralvalue}{}
 enumeration literal as it appears in the source program. 
 Each enumerator entry also has a 
 \DWATconstvalue{} attribute,
@@ -1738,9 +1695,9 @@ represented on the target system.
 If the enumeration type occurs as the description of a
 \addtoindexx{enumeration type endry!as array dimension}
 dimension of an array type, and the stride for that dimension
-\hypertarget{chap:DWATbytestrideenumerationstridedimensionofarraytype}
+\hypertarget{chap:DWATbytestrideenumerationstridedimensionofarraytype}{}
 is different than what would otherwise be determined, then
-\hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}
+\hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}{}
 the enumeration type entry has either a 
 \DWATbytestride{}
 or \DWATbitstride{} attribute 
@@ -1802,7 +1759,7 @@ declared using function prototype style declarations and
 those declared using non\dash prototype declarations.}
 
 A 
-\hypertarget{chap:DWATprototypedsubroutineprototype}
+\hypertarget{chap:DWATprototypedsubroutineprototype}{}
 subroutine entry declared with a function prototype style
 declaration may have 
 \addtoindexx{prototyped attribute}
@@ -1868,7 +1825,7 @@ storage needed to hold a value of the string type.
 
 
 The 
-\hypertarget{chap:DWATstringlengthstringlengthofstringtype}
+\hypertarget{chap:DWATstringlengthstringlengthofstringtype}{}
 string type entry may also have a 
 \DWATstringlength{} attribute
 whose 
@@ -1985,7 +1942,7 @@ is the amount of
 storage needed to hold a value of the subrange type.
 
 The 
-\hypertarget{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}
+\hypertarget{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}{}
 subrange entry may have 
 \addtoindexx{threads scaled attribute}
 a 
@@ -2003,9 +1960,9 @@ int shared foo[34*THREADS][10][20];
 \end{lstlisting}
 
 The 
-\hypertarget{chap:DWATlowerboundlowerboundofsubrange}
+\hypertarget{chap:DWATlowerboundlowerboundofsubrange}{}
 subrange 
-\hypertarget{chap:DWATupperboundupperboundofsubrange}
+\hypertarget{chap:DWATupperboundupperboundofsubrange}{}
 entry may have the attributes 
 \DWATlowerbound{}
 \addtoindexx{lower bound attribute}
@@ -2014,7 +1971,7 @@ and \DWATupperbound{}
 and upper bound values of the subrange. The 
 \DWATupperbound{}
 attribute 
-\hypertarget{chap:DWATcountelementsofsubrangetype}
+\hypertarget{chap:DWATcountelementsofsubrangetype}{}
 may 
 % FIXME: The following matches DWARF4: odd as there is no default count.
 \addtoindexx{count attribute!default}
@@ -2074,9 +2031,9 @@ integer with the same size as an address on the target machine.
 
 If the subrange type occurs as the description of a dimension
 of an array type, and the stride for that dimension is
-\hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}
+\hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}{}
 different than what would otherwise be determined, then
-\hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}
+\hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}{}
 the subrange type entry has either 
 \addtoindexx{byte stride attribute}
 a 
@@ -2118,7 +2075,7 @@ describe the type of the class or structure member to which
 objects of this type may point.
 
 The \addtoindexx{pointer to member} entry also 
-\hypertarget{chap:DWATcontainingtypecontainingtypeofpointertomembertype}
+\hypertarget{chap:DWATcontainingtypecontainingtypeofpointertomembertype}{}
 has a 
 \DWATcontainingtype{}
 attribute, whose value is a \livelink{chap:classreference}{reference} to a debugging
@@ -2126,7 +2083,7 @@ information entry for the class or structure to whose members
 objects of this type may point.
 
 The \addtoindex{pointer to member entry} 
-\hypertarget{chap:DWATuselocationmemberlocationforpointertomembertype}
+\hypertarget{chap:DWATuselocationmemberlocationforpointertomembertype}{}
 has a 
 \DWATuselocation{} attribute
 \addtoindexx{use location attribute}
@@ -2165,7 +2122,7 @@ whose address is being calculated.
     object.*mbr_ptr
 \end{lstlisting}
 \textit{where \texttt{mbr\_ptr} has some \addtoindex{pointer to member type}, a debugger should:}
-\begin{enumerate}
+\begin{enumerate}[1. ]
 \item \textit{Push the value of \texttt{mbr\_ptr} onto the DWARF expression stack.}
 \item \textit{Push the base address of \texttt{object} onto the DWARF expression stack.}
 \item \textit{Evaluate the \DWATuselocation{} description 
@@ -2216,7 +2173,7 @@ is the amount of storage need to hold a value of the file type.
 information, including a location and/or run\dash time parameters,
 about the data that represents the value for that object.}
 
-\hypertarget{chap:DWATdatalocationindirectiontoactualdata}
+\hypertarget{chap:DWATdatalocationindirectiontoactualdata}{}
 The \DWATdatalocation{} 
 attribute may be used with any
 \addtoindexx{data location attribute}
@@ -2248,7 +2205,7 @@ provide types whose values
 may be dynamically allocated or associated with a variable
 under explicit program control.}
 
-\hypertarget{chap:DWATallocatedallocationstatusoftypes}
+\hypertarget{chap:DWATallocatedallocationstatusoftypes}{}
 The 
 \DWATallocated{} 
 attribute 
@@ -2261,7 +2218,7 @@ integer value of the attribute (see below) specifies whether
 an object of the type is 
 currently allocated or not.
 
-\hypertarget{chap:DWATassociatedassociationstatusoftypes}
+\hypertarget{chap:DWATassociatedassociationstatusoftypes}{}
 The 
 \DWATassociated{} attribute 
 may 
@@ -2350,6 +2307,12 @@ fashion.
 \section{Template Alias Entries}
 \label{chap:templatealiasentries}
 
+\textit{
+In addtoindex{C++}, a template alias is a form of typedef that has template
+parameters.  DWARF does not represent the template alias definition
+but does represent instantiations of the alias.
+}
+
 A type named using a template alias is represented
 by a debugging information entry 
 \addtoindexx{template alias entry}
@@ -2360,48 +2323,7 @@ The template alias entry has a
 \addtoindexx{name attribute}
 whose value is a null\dash terminated string
 containing the name of the template alias as it appears in
-the source program. The template alias entry also contains 
-\addtoindexx{type attribute}
-a
-\DWATtype{} attribute 
-whose value is a \livelink{chap:classreference}{reference}
-to the type named by the template alias. 
-
-\needlines{4}
-The template alias entry has the following child entries:
-\begin{enumerate}[1. ]
-\item Each formal parameterized type declaration appearing
-in the template alias declaration is represented
-by a debugging information entry with the tag
-\DWTAGtemplatetypeparameter. 
-Each such entry may have
-a \DWATname{} attribute,
-\addtoindexx{name attribute}
-whose value is a null\dash terminated
-string containing the name of the formal type parameter as it
-appears in the source program. The template type parameter
-entry also has 
-\addtoindexx{type attribute}
-a \DWATtype{} attribute
-describing the actual
-type by which the formal is replaced for this instantiation.
-
-\item Each formal parameterized value declaration
-appearing in the template alias declaration is
-represented by a debugging information entry with the tag
-\DWTAGtemplatevalueparameter. 
-Each such entry may have
-a \DWATname{} attribute,
-\addtoindexx{name attribute}
-whose value is a null\dash terminated
-string containing the name of the formal value parameter
-as it appears in the source program. The template value
-parameter entry also has 
-\addtoindexx{type attribute}
-a \DWATtype{} attribute describing
-the type of the parameterized value. Finally, the template
-value parameter entry has a \DWATconstvalue{} 
-attribute, whose value is the actual constant value of the value parameter for
-this instantiation as represented on the target architecture.
-\end{enumerate}
+the source program.
+The template alias entry has child entries describing the template
+actual parameters (see Section \refersec{chap:templateparameters}).