\item A \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute,
\hypertarget{chap:DWATexternalexternalvariable}
-which is a \livelink{chap:flag}{flag}, if the name
+which
+\addtoindexx{external attribute}
+is a \livelink{chap:flag}{flag}, if the name
of a variable is visible outside of its enclosing compilation
unit. The definitions of C++ static data members of structures
or classes are represented by variable entries \nolink{flagged} as
\addtoindexx{vendor extensibility}
\addtoindexx{vendor specific extensions|see{vendor extensibility}}
-To reserve a portion of the DWARF name space and ranges of
+To
+\addtoindexx{extensibility|see{vendor extensibility}}
+reserve a portion of the DWARF name space and ranges of
enumeration values for use for vendor specific extensions,
special labels are reserved for tag names, attribute names,
base type encodings, location operations, language names,
\label{datarep:errorvalues}
\addtoindexx{reserved values!error}
-As a convenience for consumers of DWARF information, the value
+As
+\addtoindexx{error value}
+a convenience for consumers of DWARF information, the value
0 is reserved in the encodings for attribute names, attribute
forms, base type encodings, location operations, languages,
line number program opcodes, macro information entries and tag
\label{datarep:locationlists}
Each entry in a location list is either a location list entry,
-a base address selection entry, or an end of list entry.
+a base address selection entry, or an
+\addtoindex{end of list entry!in location list}
+end of list entry.
A location list entry consists of two address offsets followed
by a 2\dash byte length, followed by a block of contiguous bytes
specifies the number of bytes in that block. The two offsets
are the same size as an address on the target machine.
-A base address selection entry and an end of list entry each
+A base address selection entry and an
+\addtoindex{end of list entry!in location list}
+end of list entry each
consist of two (constant or relocated) address offsets. The two
offsets are the same size as an address on the target machine.
The encodings of the
\hypertarget{chap:DWATencodingencodingofbasetype}
-constants used in the
+constants used in
+\addtoindexx{encoding attribute!encoding}
+the
\livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding}
attribute are given in
Table \refersec{tab:basetypeencodingvalues}
A range list entry consists of two relative addresses. The
addresses are the same size as addresses on the target machine.
-A base address selection entry and an end of list entry each
+A base address selection entry and an
+\addtoindex{end of list entry!in range list}
+end of list entry each
\addtoindexx{base address selection entry!in range list}
consist of two (constant or relocated) addresses. The two
addresses are the same size as addresses on the target machine.
tag and a series of
\addtoindex{attributes}.
An entry, or group of entries together, provide a description of a
-corresponding entity in the source program.
+corresponding
+\addtoindex{entity} in the source program.
The tag specifies the class to which an entry belongs
and the attributes define the specific characteristics of the entry.
The two forms are distinguished in a context sensitive
manner. As the value of an attribute, a location description
-is encoded using class \livelink{chap:exprloc}{exprloc}
+is encoded using
+\addtoindexx{exprloc class}
+class \livelink{chap:exprloc}{exprloc}
and a location list is encoded
using class \livelink{chap:loclistptr}{loclistptr} (which serves as an offset into a
separate location list table).
\paragraph{Empty Location Descriptions}
-An empty location description consists of a DWARF expression
+An \addtoindex{empty location description}
+consists of a DWARF expression
containing no operations. It represents a piece or all of an
object that is present in the source but not in the object code
(perhaps due to optimization).
entry,
a
\addtoindexi{base}{base address selection entry!in location list}
-address selection entry, or an end of list entry.
+address selection entry, or an
+\addtoindexx{end of list entry!in location list}
+end of list entry.
A location list entry consists of:
range over which the location is valid. The ending address
must be greater than or equal to the beginning address.
-\textit{A location list entry (but not a base address selection or end of list entry) whose beginning
-and ending addresses are equal has no effect because the size of the range covered by such
+\textit{A location list entry (but not a base address selection or
+end of list entry) whose beginning
+and ending addresses are equal has no effect
+because the size of the range covered by such
an entry is zero.}
\item A single location description
The end of any given location list is marked by an end of
list entry, which consists of a 0 for the beginning address
offset and a 0 for the ending address offset. A location list
-containing only an end of list entry describes an object that
+containing only an
+\addtoindexx{end of list entry!in location list}
+end of list entry describes an object that
exists in the source code but not in the executable program.
Neither a base address selection entry nor an end of list
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},
-\livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} or \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute, or a location
+\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute has a
+\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
+\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc},
+\livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} or
+\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute,
+\addtoindexx{entry pc attribute}
+or
+a location
description that evaluates to an address, then those address
values represent the offset portion of the address within
the segment specified by \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}.
Each entry in a range list is either a range list entry,
\addtoindexx{base address selection entry!in range list}
-a base address selection entry, or an end of list entry.
+a base address selection entry, or an
+\addtoindexx{end of list entry!in range list}
+end of list entry.
A range list entry consists of:
\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
-first address past the end of the address range.The ending address must be greater than or
+first address past the end of the address range.
+The ending address must be greater than or
equal to the beginning address.
\textit{A range list entry (but not a base address selection or end of list entry) whose beginning and
affects only the list in which it is contained.}
-The end of any given range list is marked by an end of
-list entry, which consists of a 0 for the beginning address
+The end of any given range list is marked by an
+\addtoindexx{end of list entry!in range list}
+end of list entry,
+which consists of a 0 for the beginning address
offset and a 0 for the ending address offset. A range list
containing only an end of list entry describes an empty scope
(which contains no instructions).
-\textit{A base address selection entry and an end of list entry for
+\textit{A base address selection entry and an
+\addtoindexx{end of list entry!in range list}
+end of list entry for
a range list are identical to a base address selection entry
and end of list entry, respectively, for a location list
(see Section \refersec{chap:locationlists})
\addtoindex{end\_sequence} &
A boolean indicating that the current address is that of the first byte after
-the end of a sequence of target machine instructions. end\_sequence
+the end of a sequence of target machine instructions.
+\addtoindex{end\_sequence}
terminates a sequence of lines; therefore other information in the same
row is not meaningful. \\
file & 1 \\
line & 1 \\
column & 0 \\
-is\_stmt & determined by \addtoindex{default\_is\_stmt} in the line number program header \\
-basic\_block & ``false'' \addtoindexx{basic block} \\
-end\_sequence & ``false'' \\
-prologue\_end & ``false'' \\
-epilogue\_begin & ``false'' \\
+\addtoindex{is\_stmt} & determined by \addtoindex{default\_is\_stmt} in the line number program header \\
+\addtoindex{basic\_block} & ``false'' \addtoindexx{basic block} \\
+\addtoindex{end\_sequence} & ``false'' \\
+\addtoindex{prologue\_end} & ``false'' \\
+\addtoindex{epilogue\_begin} & ``false'' \\
isa & 0 \\
discriminator & 0 \\
\end{tabular}
\item Add a signed integer to the line register.
\item Modify the operation pointer by incrementing the
-address and op\_index registers as described below.
+address and \addtoindex{op\_index} registers as described below.
\item Append a row to the matrix using the current values
of the state machine registers.
-\item Set the basic\_block register to ``false.'' \addtoindexx{basic block}
-\item Set the prologue\_end register to ``false.''
-\item Set the epilogue\_begin register to ``false.''
+\item Set the \addtoindex{basic\_block} register to ``false.'' \addtoindexx{basic block}
+\item Set the \addtoindex{prologue\_end} register to ``false.''
+\item Set the \addtoindex{epilogue\_begin} register to ``false.''
\item Set the \addtoindex{discriminator} register to 0.
\end{enumerate}
\item \textbf{DW\-\_LNS\-\_set\-\_prologue\-\_end} \\
The \livetarg{chap:DWLNSsetprologueend}{DW\-\_LNS\-\_set\-\_prologue\-\_end}
-opcode takes no operands. It sets the prologue\_end register
+opcode takes no operands. It sets the
+\addtoindex{prologue\_end} register
to ``true''.
\textit{When a breakpoint is set on entry to a function, it is
location; for example, the code might test for a special case
and make a fast exit prior to setting up the frame.}
-\textit{Note that the function to which the prologue end applies cannot
+\textit{Note that the function to which the
+\addtoindex{prologue end} applies cannot
be directly determined from the line number information alone;
it must be determined in combination with the subroutine
information entries of the compilation (including inlined
\item \textbf{DW\-\_LNS\-\_set\-\_epilogue\-\_begin} \\
The \livetarg{chap:DWLNSsetepiloguebegin}{DW\-\_LNS\-\_set\-\_epilogue\-\_begin} opcode takes no operands. It
-sets the epilogue\_begin register to ``true''.
+sets the \addtoindex{epilogue\_begin} register to ``true''.
\textit{When a breakpoint is set on the exit of a function or execution
steps over the last executable statement of a function, it is
cannot properly determine where this point is. This command
allows a compiler to communicate the location(s) to use.}
-\textit{Note that the function to which the epilogue end applies cannot
+\textit{Note that the function to which the
+\addtoindex{epilogue end} applies cannot
be directly determined from the line number information alone;
it must be determined in combination with the subroutine
information entries of the compilation (including inlined
subroutines).}
-\textit{In the case of a trivial function, both prologue end and
-epilogue begin may occur at the same address.}
+\textit{In the case of a trivial function, both
+\addtoindex{prologue end} and
+\addtoindex{epilogue begin} may occur at the same address.}
\item \textbf{DW\-\_LNS\-\_set\-\_isa} \\
The \livetarg{chap:DWLNSsetisa}{DW\-\_LNS\-\_set\-\_isa} opcode takes a single
\item \textbf{DW\-\_LNE\-\_end\-\_sequence} \\
The \livetarg{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence} opcode takes no operands. It sets the
-end\_sequence register of the state machine to “true” and
+\addtoindex{end\_sequence}
+register of the state machine to “true” and
appends a row to the matrix using the current values of the
state-machine registers. Then it resets the registers to the
initial values specified above
saves the value that the register had at entry time in its call
frame and restores it on exit. The code that allocates space
on the call frame stack and performs the save operation is
-called the subroutine’s prologue, and the code that performs
+called the subroutine’s \addtoindex{prologue}, and the code that performs
the restore operation and deallocates the frame is called its
-epilogue. Typically, the prologue code is physically at the
-beginning of a subroutine and the epilogue code is at the end.}
+\addtoindex{epilogue}. Typically, the
+\addtoindex{prologue} code is physically at the
+beginning of a subroutine and the
+\addtoindex{epilogue} code is at the end.}
\textit{To be able to view or modify an activation that is not
on the top of the call frame stack, the debugger must
\begin{itemize} % bullet list
-\item \textit{Prologue and epilogue code is not always in
+\item \textit{Prologue
+\addtoindexx{prologue}
+and
+\addtoindex{epilogue} code is not always in
distinct block
at the beginning and end of a subroutine. It is common
-to duplicate the epilogue code at the site of each return
+to duplicate the \addtoindex{epilogue} code
+at the site of each return
from the code. Sometimes a compiler breaks up the register
save/unsave operations and moves them into the body of the
subroutine to just where they are needed.}
not.}
\item \textit{The algorithm to compute CFA changes as you progress through
-the prologue and epilogue code. (By definition, the CFA value
+the \addtoindex{prologue}
+and \addtoindex{epilogue code}.
+(By definition, the CFA value
does not change.)}
\item \textit{Some subroutines have no call frame.}
register and offset.
\item \textbf{DW\-\_CFA\-\_def\-\_cfa\-\_expression} \\
-The \livetarg{chap:DWCFAdefcfaexpression}{DW\-\_CFA\-\_def\-\_cfa\-\_expression} instruction takes a single
+The \livetarg{chap:DWCFAdefcfaexpression}{DW\-\_CFA\-\_def\-\_cfa\-\_expression} instruction takes a
+\addtoindexx{exprloc class}
+single
operand encoded as a \livelink{chap:DWFORMexprloc}{DW\-\_FORM\-\_exprloc} value representing a
DWARF expression. The required action is to establish that
expression as the means by which the current CFA is computed.
\textit{The next two instructions provide the ability to stack and
retrieve complete register states. They may be useful, for
-example, for a compiler that moves epilogue code into the
+example, for a compiler that moves \addtoindex{epilogue} code
+into the
body of a function.}
the module name as it appears in the source program.
The module entry may have either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
-\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of attributes or a \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
+\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}
+pair of attributes or a
+\livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} attribute
whose values encode the contiguous or non\dash contiguous address
ranges, respectively, of the machine instructions generated for
the module initialization code
(see Section \refersec{chap:codeaddressesandranges}).
\hypertarget{chap:DWATentrypcentryaddressofmoduleinitialization}
It may also
-have a \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute whose value is the address of
+\addtoindexx{entry pc attribute!for module initialization}
+have a
+\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute whose value is the address of
the first executable instruction of that initialization code
(see Section \refersec{chap:entryaddress}).
\hypertarget{chap:DWATextensionpreviousnamespaceextensionororiginalnamespace}
represented by a
\livelink{chap:DWTAGnamespace}{DW\-\_TAG\-\_namespace} entry
-with a
+with
+\addtoindexx{extension attribute}
+a
\livelink{chap:DWATextension}{DW\-\_AT\-\_extension}
attribute referring to the previous extension, or if there
is no previous extension, to the original
\section{Subroutine and Entry Point Entries}
\label{chap:subroutineandentrypointentries}
-The following tags exist to describe debugging information entries for subroutines and entry
+The following tags exist to describe
+debugging information entries for subroutines and entry
+% FIXME: is entry point entry the right index 'entry'?
+\addtoindexx{entry point entry}
points:
\begin{tabular}{lp{9.0cm}}
tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}
is visible outside of its containing
\hypertarget{chap:DWATexternalexternalsubroutine}
-compilation unit, that entry has a
+compilation unit, that entry has
+\addtoindexx{external attribute}
+a
\livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute,
which is a \livelink{chap:flag}{flag}.
A subprogram entry
\hypertarget{chap:DWATelementalelementalpropertyofasubroutine}
-may have a
+may have
+\addtoindexx{elemental attribute}
+a
\livelink{chap:DWATelemental}{DW\-\_AT\-\_elemental} attribute, which
is a \livelink{chap:flag}{flag}.
The attribute indicates whether the subroutine
A
\hypertarget{chap:DWATentrypcentryaddressofsubprogram}
-subroutine entry may also have a
+subroutine entry may also have
+\addtoindexx{entry pc attribute!for subroutine}
+a
\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute
whose value is the address of the first executable instruction
of the subroutine (see
relocated address of the first machine instruction generated
for the entry point.
-\textit{While the \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute might also seem appropriate
-for this purpose, historically the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute
-was used before the \livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} was introduced (in DWARF
-Version 3). There is insufficient reason to change this.}
+\textit{While the
+\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} attribute
+\addtoindexx{entry pc attribute!for subroutine}
+might
+also seem appropriate
+for this purpose, historically the
+\livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} attribute
+was used before the
+\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc} was introduced (in
+\addtoindex{DWARF Version 3}).
+There is insufficient reason to change this.}
Subroutines
it may validly throw.}
If a subroutine explicitly declares that it may throw
+\addtoindexx{exception thrown|see{thrown type entry}}
an exception for one or more types, each such type is
-represented by a debugging information entry with the tag
+represented by a debugging information entry with
+\addtoindexx{thrown type entry}
+the tag
\livetarg{chap:DWTAGthrowntype}{DW\-\_TAG\-\_thrown\-\_type}.
Each such entry is a child of the entry
representing the subroutine that may throw this type. Each
instance tree should not contain any attributes which describe
aspects of the subroutine which vary between distinct inlined
expansions or distinct out\dash of\dash line expansions. For example,
+\addtoindexx{entry pc attribute!and abstract instance}
the \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc},
-\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc}, \livelink{chap:DWATranges}{DW\-\_AT\-\_ranges},
-\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}, \livelink{chap:DWATlocation}{DW\-\_AT\-\_location},
+\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc},
+\livelink{chap:DWATranges}{DW\-\_AT\-\_ranges},
+\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc},
+\livelink{chap:DWATlocation}{DW\-\_AT\-\_location},
\livelink{chap:DWATreturnaddr}{DW\-\_AT\-\_return\-\_addr}, \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope}, and
\livelink{chap:DWATsegment}{DW\-\_AT\-\_segment}
attributes typically should be omitted; however, this list
Section \refersec{chap:codeaddressesandranges}).
An
\hypertarget{chap:DWATentrypcentryaddressofinlinedsubprogram}
-inlined subroutine entry may also contain a
+inlined subroutine entry may also contain
+\addtoindexx{entry pc attribute!for inlined subprogram}
+a
\livelink{chap:DWATentrypc}{DW\-\_AT\-\_entry\-\_pc}
attribute, representing the first executable instruction of
the inline expansion (see
as recognized by the programming language of the compilation
unit containing the base type entry.
-A base type entry has a \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} attribute describing
+A base type entry has
+\addtoindexx{encoding attribute}
+a \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} attribute describing
how the base type is encoded and is to be interpreted. The
value of this attribute is an integer constant. The set of
values and their meanings for the \livelink{chap:DWATencoding}{DW\-\_AT\-\_encoding} attribute
\addtoindexx{void type|see{unspecified type entry}}
Some languages have constructs in which a type
may be left unspecified or the absence of a type
-
may be explicitly indicated.
An unspecified (implicit, unknown, ambiguous or nonexistent)
Each array dimension is described by a debugging information
-entry with either the tag \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type} or the tag
+entry with either the tag \livelink{chap:DWTAGsubrangetype}{DW\-\_TAG\-\_subrange\-\_type} or the
+\addtoindexx{enumeration type entry!as array dimension}
+tag
\livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type}. These entries are
children of the
array type entry and are ordered to reflect the appearance of
\addtoindexx{derived type (C++)|see{inheritance entry}}
be ``derived from'' or be a
``subclass of'' another class. In Java, an interface may ``extend''
+\addtoindexx{extended type (Java)|see{inheritance entry}}
one or more other interfaces, and a class may ``extend'' another
class and/or ``implement'' one or more interfaces. All of these
relationships may be described using the following. Note that
If
\hypertarget{chap:DWATexplicitexplicitpropertyofmemberfunction}
the member function entry describes an explicit member
-function, then that entry has a
+function, then that entry has
+\addtoindexx{explicit attribute}
+a
\livelink{chap:DWATexplicit}{DW\-\_AT\-\_explicit} attribute.
An
attribute whose integer constant value is the number of bytes
required to hold an instance of the enumeration.
-The enumeration type entry may have a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
+The \addtoindex{enumeration type entry}
+may have a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute
which refers to the underlying data type used to implement
the enumeration.
-If an enumeration type has type safe semantics such that
+If an enumeration type has type safe
+semantics such that
\begin{enumerate}[1.]
\item Enumerators are contained in the scope of the enumeration type, and/or
\item Enumerators are not implicitly converted to another type
\end{enumerate}
-then the enumeration type entry may have a \livelink{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}
+then the \addtoindex{enumeration type entry} may
+\addtoindexx{enum class|see{type-safe enumeration}}
+have a \livelink{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}
attribute, which is a \livelink{chap:flag}{flag}.
In a language that offers only
one kind of enumeration declaration, this attribute is not
the underlying type will be the appropriate
integral type determined by the compiler from the properties of
\hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}
-the enumeration literal values. A \addtoindex{C++} type declaration written
+the enumeration literal values.
+A \addtoindex{C++} type declaration written
using enum class declares a strongly typed enumeration and
is represented using \livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type}
in combination with \livelink{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}.}
Each enumeration literal is represented by a debugging
+\addtoindexx{enumeration literal|see{enumeration entry}}
information entry with the
tag \livetarg{chap:DWTAGenumerator}{DW\-\_TAG\-\_enumerator}.
Each
-such entry is a child of the enumeration type entry, and the
+such entry is a child of the
+\addtoindex{enumeration type entry}, and the
enumerator entries appear in the same order as the declarations
of the enumeration literals in the source program.
-Each enumerator entry has a
+Each \addtoindex{enumerator entry} has a
\livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose
value is a null\dash terminated string containing the name of the
\hypertarget{chap:DWATconstvalueenumerationliteralvalue}
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}
is different than what would otherwise be determined, then
DWARF Git Projects / dwarf-doc.git / commitdiff