Signed-off-by: Ron Brender <ron.brender@gmail.com>
[dwarf-doc.git] / dwarf5 / latexdoc / generaldescription.tex
index f77e12b..76dc3ce 100644 (file)
@@ -26,7 +26,6 @@ described in Chapters 3, 4 and 5.
 
 % These each need to link to definition page: FIXME
 
-
 \begin{table}[p]
 \caption{Tag names}
 \label{tab:tagnames}
@@ -119,6 +118,18 @@ in the \dotdebuginfo{} and
 \dotdebugtypes{}
 sections of an object file.
 
+\needlines{7}
+Optionally, debugging information may be partitioned such
+that the majority of the debugging information can remain in
+individual object files without being processed by the
+linker. These debugging information entries are contained in
+the \dotdebuginfodwo{} and \dotdebugtypesdwo{} sections. These
+sections may be placed in the object file but marked so that
+the linker ignores them, or they may be placed in a separate
+DWARF object file that resides alongside the normal object
+file. See Section \refersec{datarep:splitdwarfobjects} and
+Appendix \refersec{app:splitdwarfobjectsinformative} for details.
+
 
 \section{Attribute Types}
 \label{chap:attributetypes}
@@ -176,6 +187,8 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \DWATaddressclassTARG
 &\livelinki{chap:DWATadressclasspointerorreferencetypes}{Pointer or reference types}{pointer or reference types}  \\
 &\livelinki{chap:DWATaddressclasssubroutineorsubroutinetype}{Subroutine or subroutine type}{subroutine or subroutine type} \\
+\DWATaddrbaseTARG
+&\livelinki{chap:DWATaddrbaseforaddresstable}{Base offset for address table}{address table} \\
 \DWATallocatedTARG
 &\livelinki{chap:DWATallocatedallocationstatusoftypes}{Allocation status of types}{allocation status of types}  \\
 \DWATartificialTARG
@@ -193,7 +206,6 @@ actually declared in the source}{objects or types that are not actually declared
 \DWATbitsizeTARG{} 
 &\livelinki{chap:DWATbitsizebasetypebitsize}{Base type bit size}{base type bit size} \\
 &\livelinki{chap:DWATbitsizedatamemberbitsize}{Data member bit size}{data member bit size} \\
-\newpage
 \DWATbitstrideTARG{} 
 &\livelinki{chap:DWATbitstridearrayelementstrideofarraytype}{Array element stride (of array type)}{array element stride (of array type)} \\
 &\livelinki{chap:DWATbitstridesubrangestridedimensionofarraytype}{Subrange stride (dimension of array type)}{subrange stride (dimension of array type)} \\
@@ -259,6 +271,10 @@ actually declared in the source}{objects or types that are not actually declared
 &\livelinki{chap:DWATdiscrlistlistofdiscriminantvalues}{List of discriminant values}{list of discriminant values} \\
 \DWATdiscrvalueTARG
 &\livelinki{chap:DWATdiscrvaluediscriminantvalue}{Discriminant value}{discriminant value} \\
+\DWATdwoidTARG
+&\livelinki{chap:DWATdwoidforunit}{Signature for compilation unit}{split DWARF object file!unit signature} \\
+\DWATdwonameTARG
+&\livelinki{chap:DWATdwoidforunit}{Name of split DWARF object file}{split DWARF object file!object file name} \\
 \DWATelementalTARG
 &\livelinki{chap:DWATelementalelementalpropertyofasubroutine}{Elemental property of a subroutine}{elemental property of a subroutine} \\
 \DWATencodingTARG
@@ -266,9 +282,7 @@ actually declared in the source}{objects or types that are not actually declared
 \DWATendianityTARG
 &\livelinki{chap:DWATendianityendianityofdata}{Endianity of data}{endianity of data} \\
 \DWATentrypcTARG
-&\livelinki{chap:DWATentrypcentryaddressofmoduleinitialization}{Entry address of module initialization}{entry address of module initialization}\\
-&\livelinki{chap:DWATentrypcentryaddressofsubprogram}{Entry address of subprogram}{entry address of subprogram} \\
-&\livelinki{chap:DWATentrypcentryaddressofinlinedsubprogram}{Entry address of inlined subprogram}{entry address of inlined subprogram}\\
+&\livelinki{chap:entryaddressofscope}{Entry address of a scope (compilation unit, \mbox{subprogram,} and so on)}{} \\
 \DWATenumclassTARG
 &\livelinki{chap:DWATenumclasstypesafeenumerationdefinition}{Type safe enumeration definition}{type safe enumeration definition}\\
 \DWATexplicitTARG
@@ -335,6 +349,8 @@ actually declared in the source}{objects or types that are not actually declared
 &\livelinki{chap:DWATpurepurepropertyofasubroutine}{Pure property of a subroutine}{pure property of a subroutine} \\
 \DWATrangesTARG
 &\livelinki{chap:DWATrangesnoncontiguousrangeofcodeaddresses}{Non-contiguous range of code addresses}{non-contiguous range of code addresses} \\
+\DWATrangesbaseTARG
+&\livelinki{chap:DWATrangesbaseforrangelists}{Base offset for range lists}{Ranges lists} \\
 \DWATrankTARG
 &\livelinki{chap:DWATrankofdynamicarray}{Dynamic number of array dimensions}{dynamic number of array dimensions} \\
 \DWATrecursiveTARG
@@ -367,6 +383,8 @@ actually declared in the source}{objects or types that are not actually declared
 \DWATstringlengthbytesizeTARG
 &\livelinki{chap:DWATstringlengthstringlengthofstringtype}{Size of string length of string type}{string length of string type!size of}
  \\
+\DWATstroffsetsbaseTARG
+&\livelinki{chap:DWATstroffsetbaseforindirectstringtable}{Base of string offsets table}{string offsets table} \\
 \DWATthreadsscaledTARG
 &\livelink{chap:DWATthreadsscaledupcarrayboundthreadsscalfactor}{UPC!array bound THREADS scale factor}\\
 \DWATtrampolineTARG
@@ -564,7 +582,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}
+\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 
@@ -654,31 +672,48 @@ value is truncated to the element size and the low\dash order bits
 are pushed on the stack.
 \begin{enumerate}[1. ]
 \itembfnl{\DWOPlitzeroTARG, \DWOPlitoneTARG, \dots, \DWOPlitthirtyoneTARG}
-The \DWOPlitnTARG{} operations encode the unsigned literal values
+The \DWOPlitnNAME{} operations encode the unsigned literal values
 from 0 through 31, inclusive.
 
 \itembfnl{\DWOPaddrTARG}
-The \DWOPaddrTARG{} operation has a single operand that encodes
+The \DWOPaddrNAME{} operation has a single operand that encodes
 a machine address and whose size is the \addtoindex{size of an address}
 on the target machine.
 
 \itembfnl{\DWOPconstoneuTARG, \DWOPconsttwouTARG, \DWOPconstfouruTARG, \DWOPconsteightuTARG}
-\DWOPconstnxMARK\DWOPconstnxINDX{}
-The single operand of a \DWOPconstnuTARG{} operation provides a 1,
+\DWOPconstnxMARK{}
+The single operand of a \DWOPconstnuNAME{} operation provides a 1,
 2, 4, or 8\dash byte unsigned integer constant, respectively.
 
 \itembfnl{\DWOPconstonesTARG, \DWOPconsttwosTARG, \DWOPconstfoursTARG, \DWOPconsteightsTARG}
-The single operand of a \DWOPconstnsTARG{} operation provides a 1,
+The single operand of a \DWOPconstnsNAME{} operation provides a 1,
 2, 4, or 8\dash byte signed integer constant, respectively.
 
 \itembfnl{\DWOPconstuTARG}
-The single operand of the \DWOPconstuTARG{} operation provides
+The single operand of the \DWOPconstuNAME{} operation provides
 an unsigned LEB128 integer constant.
 
 \itembfnl{\DWOPconstsTARG}
-The single operand of the \DWOPconstsTARG{} operation provides
+The single operand of the \DWOPconstsNAME{} operation provides
 a signed LEB128 integer constant.
 
+\itembfnl{\DWOPaddrxTARG}
+The \DWOPaddrxNAME{} operation has a single operand that
+encodes an unsigned LEB128 value, which is a zero-based
+index into the \dotdebugaddr{} section, where a machine
+address is stored.
+
+\itembfnl{\DWOPconstxTARG}
+The \DWOPconstxNAME{} operation has a single operand that
+encodes an unsigned LEB128 value, which is a zero-based
+index into the \dotdebugaddr{} section, where a constant, the
+size of a machine address, is stored.
+
+\textit{The \DWOPconstxNAME{} operation is provided for constants that
+require link-time relocation but should not be
+interpreted by the consumer as a relocatable address
+(for example, offsets to thread-local storage).}
+
 \end{enumerate}
 
 
@@ -1180,12 +1215,12 @@ to other pieces.
 describe
 \addtoindexx{location description!use in location list}
 objects that have a limited lifetime or change their location
-during their lifetime. Location lists are more completely
-described below.
+during their lifetime. Location lists are described in
+Section \refersec{chap:locationlists} below.
 
 \end{enumerate}
 
-The two forms are distinguished in a context sensitive
+Location descriptions are distinguished in a context sensitive
 manner. As the value of an attribute, a location description
 is encoded using 
 \addtoindexx{exprloc class}
@@ -1241,6 +1276,7 @@ Section \refersec{chap:dwarfexpressions}
 a piece or all of an object or other entity in memory.
 
 \subsubsubsection{Register Location Descriptions}
+\label{chap:registerlocationdescriptions}
 A register location description consists of a register name
 operation, which represents a piece or all of an object
 located in a given register.
@@ -1317,8 +1353,61 @@ and is at the top of the DWARF expression stack. In this form
 of location description, the DWARF expression represents the
 actual value of the object, rather than its location. The
 \DWOPstackvalueINDX{} operation terminates the expression.
+
+\itembfnl{\DWOPimplicitpointerTARG}
+The \DWOPimplicitpointerNAME{} operation specifies that the object
+is a pointer that cannot be represented as a real pointer,
+even though the value it would point to can be described. In
+this form of location description, the DWARF expression refers
+to a debugging information entry that represents the actual
+value of the object to which the pointer would point. Thus, a
+consumer of the debug information would be able to show the
+value of the dereferenced pointer, even when it cannot show
+the value of the pointer itself.
+
+\needlines{5}
+The \DWOPimplicitpointerNAME{} operation has two operands: a 
+reference to a debugging information entry that describes 
+the dereferenced object's value, and a signed number that 
+is treated as a byte offset from the start of that value. 
+The first operand is a 4-byte unsigned value in the 32-bit 
+DWARF format, or an 8-byte unsigned value in the 64-bit 
+DWARF format (see Section 
+\refersec{datarep:32bitand64bitdwarfformats}).
+The second operand is a \addtoindex{signed LEB128} number.
+
+The first operand is used as the offset of a debugging
+information entry in a \dotdebuginfo{} section, which may be
+contained in a shared object or executable other than that
+containing the operator. For references from one shared object
+or executable to another, the relocation must be performed by
+the consumer.
+
+\textit{The debugging information entry referenced by a 
+\DWOPimplicitpointerNAME{} operation is typically a
+\DWTAGvariable{} or \DWTAGformalparameter{} entry whose
+\DWATlocation{} attribute gives a second DWARF expression or a
+location list that describes the value of the object, but the
+referenced entry may be any entry that contains a \DWATlocation{}
+or \DWATconstvalue{} attribute (for example, \DWTAGdwarfprocedure).
+By using the second DWARF expression, a consumer can
+reconstruct the value of the object when asked to dereference
+the pointer described by the original DWARF expression
+containing the \DWOPimplicitpointer{} operation.}
+
 \end{enumerate}
 
+\textit{DWARF location expressions are intended to yield the \textbf{location}
+of a value rather than the value itself. An optimizing compiler
+may perform a number of code transformations where it becomes
+impossible to give a location for a value, but remains possible
+to describe the value itself. 
+Section \refersec{chap:registerlocationdescriptions}
+describes operators that can be used to
+describe the location of a value when that value exists in a
+register but not in memory. The operations in this section are
+used to describe values that exist neither in memory nor in a
+single register.}
 
 \paragraph{Empty Location Descriptions}
 
@@ -1454,6 +1543,16 @@ contents of r3 and r4.
 
 \subsection{Location Lists}
 \label{chap:locationlists}
+There are two forms of location lists. The first form 
+is intended for use in other than a split DWARF object,
+while the second is intended for use in a split DWARF object
+(see Section \refersec{datarep:splitdwarfobjects}). The two
+forms are otherwise equivalent.
+
+\textit{The form for split DWARF objects is new in \DWARFVersionV.}
+
+\subsubsection{Location Lists in Non-split Objects}
+\label{chap:locationlistsinnonsplitobjects}
 Location lists 
 \addtoindexx{location list}
 are used in place of location expressions
@@ -1613,11 +1712,63 @@ selection entry and end of list entry, respectively, for a
 in interpretation
 and representation.}
 
+\subsubsection{Location Lists in Split Objects}
+\label{chap:locationlistsinsplitobjects}
+In a split DWARF object (see 
+Section \refersec{datarep:splitdwarfobjects}), 
+location lists are contained in the \dotdebuglocdwo{} section.
+
+Each entry in the location list
+begins with a type code, which is a single byte that
+identifies the type of entry. There are five types of entries:
+\begin{enumerate}
+\itembfnl{\DWLLEendoflistentryTARG}
+This entry indicates the end of a location list, and
+contains no further data.
+
+\itembfnl{\DWLLEbaseaddressselectionentryTARG}
+This entry contains an unsigned LEB128 value immediately
+following the type code. This value is the index of an
+address in the \dotdebugaddr{} section, which is then used as
+the base address when interpreting offsets in subsequent
+location list entries of type \DWLLEoffsetpairentry.
+
+\itembfnl{\DWLLEstartendentryTARG}
+This entry contains two unsigned LEB128 values
+immediately following the type code. These values are the
+indexes of two addresses in the \dotdebugaddr{} section.
+These indicate the starting and ending addresses,
+respectively, that define the address range for which
+this location is valid. The starting and ending addresses
+given by this type of entry are not relative to the
+compilation unit base address. A single location
+description follows the fields that define the address range.
+
+\itembfnl{\DWLLEstartlengthentryTARG}
+This entry contains one LEB128 value and a 4-byte
+unsigned value immediately following the type code. The
+first value is the index of an address in the \dotdebugaddr{}
+section, which marks the beginning of the address range
+over which the location is valid. The second value is the
+length of the range. The starting address given by this
+type of entry is not relative to the compilation unit
+base address. A single location
+description follows the fields that define the address range.
+
+\itembfnl{\DWLLEoffsetpairentryTARG}
+This entry contains two 4-byte unsigned values
+immediately following the type code. These values are the
+starting and ending offsets, respectively, relative to
+the applicable base address, that define the address
+range for which this location is valid. A single location
+description follows the fields that define the address range.
+\end{enumerate}
+
 
 \section{Types of Program Entities}
 \label{chap:typesofprogramentities}
 Any 
-\hypertarget{chap:DWATtypetypeofdeclaration}
+\hypertarget{chap:DWATtypetypeofdeclaration}{}
 debugging information entry describing a declaration that
 has a type has 
 \addtoindexx{type attribute}
@@ -1648,7 +1799,7 @@ entity. The accessibility specifies which classes of other
 program objects are permitted access to the object in question.}
 
 The accessibility of a declaration is 
-\hypertarget{chap:DWATaccessibilitycandadadeclarations}
+\hypertarget{chap:DWATaccessibilitycandadadeclarations}{}
 represented by a 
 \DWATaccessibility{} 
 attribute, whose
@@ -1672,7 +1823,7 @@ visible outside of the entity in which they are
 declared.}
 
 The 
-\hypertarget{chap:DWATvisibilityvisibilityofdeclaration}
+\hypertarget{chap:DWATvisibilityvisibilityofdeclaration}{}
 visibility of a declaration is represented 
 by a \DWATvisibility{}
 attribute\addtoindexx{visibility attribute}, whose value is a
@@ -1691,14 +1842,14 @@ Table \refersec{tab:visibilitycodes}.
 member functions and for virtual base classes.}
 
 The 
-\hypertarget{chap:DWATvirtualityvirtualityindication}
+\hypertarget{chap:DWATvirtualityvirtualityindication}{}
 virtuality of a declaration is represented by a
 \DWATvirtuality{}
 attribute\addtoindexx{virtuality attribute}, whose value is a constant drawn
 from the set of codes listed in 
 Table \refersec{tab:virtualitycodes}.
 
-\begin{simplenametable}[2.4in]{Virtuality codes}{tab:virtualitycodes}
+\begin{simplenametable}[2.5in]{Virtuality codes}{tab:virtualitycodes}
 \DWVIRTUALITYnoneTARG{}                      \\
 \DWVIRTUALITYvirtualTARG{}                \\
 \DWVIRTUALITYpurevirtualTARG{}    \\
@@ -1721,7 +1872,7 @@ Any debugging information entry representing the
 \addtoindexx{artificial attribute}
 declaration of an object or type artificially generated by
 a compiler and not explicitly declared by the source program
-\hypertarget{chap:DWATartificialobjectsortypesthat}
+\hypertarget{chap:DWATartificialobjectsortypesthat}{}
 may have a 
 \DWATartificial{} attribute, 
 which is a \livelink{chap:classflag}{flag}.
@@ -1738,7 +1889,7 @@ rather than as locations within a single flat
 address space.}
 
 Any debugging information entry that contains a description
-\hypertarget{chap:DWATsegmentaddressinginformation}
+\hypertarget{chap:DWATsegmentaddressinginformation}{}
 of the location of an object or subroutine may have
 a 
 \DWATsegment{} attribute, 
@@ -1825,7 +1976,7 @@ entity. In certain contexts, however, a debugger might need
 information about a declaration of an entity that is not
 \addtoindexx{incomplete declaration}
 also a definition, or is otherwise incomplete, to evaluate
-\hypertarget{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}
+\hypertarget{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}{}
 an expression correctly.
 
 \textit{As an example, consider the following fragment of \addtoindex{C} code:}
@@ -1861,7 +2012,7 @@ attribute, which is a
 
 \subsection{Declarations Completing Non-Defining Declarations}
 A debugging information entry that represents a 
-\hypertarget{chap:DWATspecificationincompletenondefiningorseparatedeclaration}
+\hypertarget{chap:DWATspecificationincompletenondefiningorseparatedeclaration}{}
 declaration that completes another (earlier) 
 non\dash defining declaration may have a 
 \DWATspecification{}
@@ -1897,11 +2048,11 @@ entry.}
 a declaration with its occurrence in the program source.}
 
 Any debugging information 
-\hypertarget{chap:DWATdeclfilefilecontainingsourcedeclaration}
+\hypertarget{chap:DWATdeclfilefilecontainingsourcedeclaration}{}
 entry 
-\hypertarget{chap:DWATdecllinelinenumberofsourcedeclaration}
+\hypertarget{chap:DWATdecllinelinenumberofsourcedeclaration}{}
 representing 
-\hypertarget{chap:DWATdeclcolumncolumnpositionofsourcedeclaration}
+\hypertarget{chap:DWATdeclcolumncolumnpositionofsourcedeclaration}{}
 the
 \addtoindexx{line number of declaration}
 declaration of an object, module, subprogram or
@@ -1948,7 +2099,7 @@ indicates that no column has been specified.
 \section{Identifier Names}
 \label{chap:identifiernames}
 Any 
-\hypertarget{chap:DWATnamenameofdeclaration}
+\hypertarget{chap:DWATnamenameofdeclaration}{}
 debugging information entry 
 \addtoindexx{identifier names}
 representing 
@@ -1975,7 +2126,7 @@ DWARF \DWATname{} attribute,
 \addtoindexx{name attribute}
 including the keyword operator (in names such as \doublequote{operator +}),
 if present. See also 
-Section \refersec{chap:linkagenames} regarding the use
+Section \referfol{chap:linkagenames} regarding the use
 of \DWATlinkagename{} for 
 \addtoindex{mangled names}
 mangled names. 
@@ -1984,7 +2135,7 @@ multiple whitespace characters may be compressed.}
 
 \section{Data Locations and DWARF Procedures}
 Any debugging information entry describing a data object (which
-\hypertarget{chap:DWATlocationdataobjectlocation}
+\hypertarget{chap:DWATlocationdataobjectlocation}{}
 includes variables and parameters) or 
 \livelink{chap:commonblockentry}{common blocks}
 may have 
@@ -2026,13 +2177,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}
+\hypertarget{chap:DWATrangesnoncontiguousrangeofcodeaddresses}{}
 subroutines, ordinary \nolink{blocks}, 
 try/catch \nolink{blocks} (see Section\refersec{chap:tryandcatchblockentries}), 
 labels and the like, may have
 \begin{itemize}
 \item A \DWATlowpc{} attribute for
-\hypertarget{chap:DWATlowpccodeaddressorrangeofaddresses}
+\hypertarget{chap:DWATlowpccodeaddressorrangeofaddresses}{}
 a single address,
 
 \item A \DWATlowpc{}
@@ -2040,7 +2191,7 @@ a single address,
 and 
 \DWAThighpc{}
 \addtoindexx{high PC attribute}
-\hypertarget{chap:DWAThighpccontiguousrangeofcodeaddresses}
+\hypertarget{chap:DWAThighpccontiguousrangeofcodeaddresses}{}
 pair of attributes for 
 a single contiguous range of
 addresses, or
@@ -2118,8 +2269,7 @@ a \DWATstartscope{} attribute
 may have a value of class
 \livelink{chap:classrangelistptr}{rangelistptr} for the same reason.  
 
-Range lists are contained
-in a separate object file section called 
+Range lists are contained in a separate object file section called 
 \dotdebugranges{}. A
 \addtoindex{range list} is indicated by a 
 \DWATranges{} attribute whose
@@ -2128,6 +2278,18 @@ value is represented as an offset from the beginning of the
 \dotdebugranges{} section to the beginning of the 
 \addtoindex{range list}.
 
+If the current compilation unit contains a \DWATrangesbase{}
+attribute, the value of that attribute establishes a base
+offset within the \dotdebugranges{} section for the compilation
+unit. The offset given by the \DWATranges{} attribute is
+relative to that base.
+
+\textit{The \DWATrangesbase{} attribute is new in \addtoindex{DWARF Version 5}.
+The advantage of this attribute is that is reduces the number of
+object language relocations needed for references to the \dotdebugranges{}
+section from one for each reference to a single relocation that
+applies for the entire compilation unit.}
+
 Each entry in a \addtoindex{range list} is either a 
 \addtoindex{range list} entry,
 \addtoindexx{base address selection entry!in range list}
@@ -2221,12 +2383,22 @@ Any debugging information entry describing an entity that has
 a range of code addresses, which includes compilation units,
 module initialization, subroutines, 
 ordinary \livelink{chap:lexicalblock}{block}, 
-try/catch \nolink{blocks} (see Section \refersec{chap:tryandcatchblockentries}),
-and the like, 
-may have a \DWATentrypc{} attribute to
+try/catch \nolink{blocks} (see Section 
+\refersec{chap:tryandcatchblockentries}),
+and the like, may have a \DWATentrypcNAME{} attribute to
 indicate the first executable instruction within that range
-of addresses. The value of the \DWATentrypc{} attribute is a
-relocated address. If no \DWATentrypc{} attribute is present,
+\hypertarget{chap:entryaddressofscope}{}
+of addresses. The value of the \DWATentrypcNAME{} attribute is a
+relocated address if the
+value of \DWATentrypcNAME{} is of class address; or if it is of class
+constant, the value is an unsigned integer offset which, when
+added to the base address of the function, gives the entry
+address. 
+
+The base address of the containing scope is given by either the
+\DWATlowpc{} attribute, or the first range entry in the list of
+ranges given by the \DWATranges{} attribute. 
+If no \DWATentrypcNAME{} attribute is present,
 then the entry address is assumed to be the same as the
 value of the \DWATlowpc{} attribute, if present; otherwise,
 the entry address is unknown.
@@ -2287,7 +2459,7 @@ type descriptions of the form typename\textquoteright Class, and
 
 Generally, any debugging information
 entry that 
-\hypertarget{chap:DWATdescriptionartificialnameordescription}
+\hypertarget{chap:DWATdescriptionartificialnameordescription}{}
 has, or may have, 
 \addtoindexx{name attribute}
 a 
@@ -2348,7 +2520,7 @@ 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}
+\hypertarget{chap:DWATlinkagenameobjectfilelinkagenameofanentity}{}
 that is encoded in the linkage name itself.  
 }
 
@@ -2368,3 +2540,62 @@ may apply include: \DWTAGcommonblock, \DWTAGconstant,
 \DWTAGentrypoint, \DWTAGsubprogram{} 
 and \DWTAGvariable.
 }
+
+\section{Template Parameters}
+\label{chap:templateparameters}
+\textit{
+In \addtoindex{C++}, a template is a generic definition of a class, function, member
+function, or typedef (alias).  A template has formal parameters that
+can be types or constant values; the class, function,
+member function, or typedef is instantiated differently for each
+distinct combination of type or value actual parameters.  DWARF does
+not represent the generic template definition, but does represent each
+instantiation.
+}
+
+A debugging information entry that represents a 
+\addtoindex{template instantiation}
+will contain child entries describing the actual template parameters.
+The containing entry and each of its child entries reference a template
+parameter entry in any circumstance where the template definition
+referenced a formal template parameter.
+
+A template type parameter is represented by a debugging information
+entry with the tag
+\addtoindexx{template type parameter entry}
+\DWTAGtemplatetypeparameterTARG. 
+A template value parameter is represented by a debugging information
+entry with the tag
+\addtoindexx{template value parameter entry}
+\DWTAGtemplatevalueparameterTARG.
+The actual template parameter entries appear in the same order as the 
+corresponding template formal parameter declarations in the 
+source program.
+
+\needlines{4}
+A type or value parameter entry may have a \DWATname{} attribute, 
+\addtoindexx{name attribute}
+whose value is a
+null\dash terminated string containing the name of the corresponding 
+formal parameter as it appears in the source program. 
+
+A
+\addtoindexx{formal type parameter|see{template type parameter entry}}
+template type parameter entry has a
+\addtoindexx{type attribute}
+\DWATtype{} attribute
+describing the actual type by which the formal is replaced.
+
+A value parameter entry has an attribute giving the 
+actual compile-time or run-time constant value 
+of the value parameter for this instantiation.
+This can be a \DWATconstvalue{} attribute, whose
+value is the compile-time constant value as represented 
+on the target architecture. 
+Or, it can a \DWATlocation{} attribute, whose value is a 
+single location description for the run-time constant address.
+The entry may also have a 
+\DWATdefaultvalue{} attribute, which is a flag indicating 
+that the value corresponds to the default argument for the 
+template parameter.
+