\end{table}
-\textit{The debugging information entry descriptions
-in Sections 3, 4 and 5 generally include mention of
+\textit{The debugging information entry descriptions in
+\bb
+Chapters
+\eb
+3, 4 and 5 generally include mention of
most, but not necessarily all, of the attributes
that are normally or possibly used with the entry.
Some attributes, whose applicability tends to be
The debugging information entries are contained in the
\dotdebuginfo{} and/or \dotdebuginfodwo{} sections of an object file.
-\needlines{7}
+\needlines{4}
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{} 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:splitdwarfobjectfiles} and
+linker.
+\bb\eb
+See Section \refersec{datarep:splitdwarfobjectfiles} and
Appendix \refersec{app:splitdwarfobjectsinformative} for details.
+\needlines{4}
As a further option, debugging information entries and other debugging
information that are the same in multiple executable or shared object files
may be found in a separate \addtoindex{supplementary object file} that
contains supplementary debug sections.
-The executable or shared object file which contains references to
-those debugging information entries contain a \dotdebugsup{} section
-with information that identifies the \addtoindex{supplementary object file};
-the \addtoindex{supplementary object file} contains a variant of this same section
-that is used to unambiguously associate it with the referencing object.
+\bb\eb
See Section \refersec{datarep:dwarfsupplemetaryobjectfiles} for
further details.
\DWATbitstrideTARG{}
&\livelinki{chap:DWATbitstridearrayelementstrideofarraytype}
{Array element stride (of array type)}
- {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)} \\
+ {subrange stride (dimension of array type)} \\*
&\livelinki{chap:DWATbitstrideenumerationstridedimensionofarraytype}
{Enumeration stride (dimension of array type)}
{enumeration stride (dimension of array type)} \\
\addtoindexx{class of attribute value!string|see {string class}}
\addtoindexx{class of attribute value!stroffsetsptr|see {stroffsetsptr class}}
+\needlines{6}
The permissible values
\addtoindexx{attribute value classes}
for an attribute belong to one or more classes of attribute
\doublequote{Constant data}
is the class of attribute value that those attributes may have.
There are several representations of constant data,
-however (one, two, four, or eight bytes, and variable length
-data).
+\bb
+including fixed length data of one, two, four, eight or 16 bytes
+in size,
+\eb
+and variable length data).
The particular representation for any given instance
of an attribute is encoded along with the attribute name as
part of the information that guides the interpretation of a
\hypertarget{chap:classaddrptr}{}
\livelinki{datarep:classaddrptr}{addrptr}{addrptr class}
-&Refers to a base location in the DWARF section that holds
-a series of machine address values. Certain attributes \mbox{refer}
-one of these addresses by indexing relative to this base
-location.
+&
+\bb
+Specifies a location in the DWARF section that holds
+a series of machine address values. Certain attributes use
+one of these addresses by indexing relative to this location.
+\eb
\\
\hypertarget{chap:classblock}{}
\hypertarget{chap:classconstant}{}
\livelinki{datarep:classconstant}{constant}{constant class}
-&One, two, four or eight bytes of uninterpreted data, or data
+&One, two, four, eight
+\bb
+or sixteen
+\eb
+bytes of uninterpreted data, or data
encoded in the variable length format known as LEB128
(see Section \refersec{datarep:variablelengthdata}).
-
-\textit{Most constant values are integers of one kind or
-another (codes, offsets, counts, and so on); these are
-sometimes called \doublequote{integer constants} for emphasis.}
-\addtoindexx{integer constant}
-\addtoindexx{constant class!integer}
\\
\hypertarget{chap:classexprloc}{}
\hypertarget{chap:classlineptr}{}
\livelinki{datarep:classlineptr}{lineptr}{lineptr class}
-&Refers to a location in the DWARF section that holds line number information.
+&
+\bb
+Specifies
+\eb
+a location in the DWARF section that holds line number information.
\\
\hypertarget{chap:classloclistptr}{}
\livelinki{datarep:classloclistptr}{loclistptr}{loclistptr class}
-&Refers to a location in the DWARF section that holds \mbox{location} lists, which
+&
+\bb
+Specifies
+\eb
+a location in the DWARF section that holds \mbox{location} lists, which
describe objects whose location can change during their lifetime.
\\
\hypertarget{chap:classmacptr}{}
\livelinki{datarep:classmacptr}{macptr}{macptr class}
-& Refers to a location in the DWARF section that holds macro definition
- information.
+&
+\bb
+Specifies
+\eb
+a location in the DWARF section that holds macro definition
+information.
\\
\hypertarget{chap:classrangelistptr}{}
\livelinki{datarep:classrangelistptr}{rangelistptr}{rangelistptr class}
-& Refers to a location in the DWARF section that holds non\dash contiguous address ranges.
+&
+\bb
+Specifies
+\eb
+a location in the DWARF section that holds non-contiguous address ranges.
\\
\hypertarget{chap:classreference}{}
\livelinki{datarep:classreference}{reference}{reference class}
-& Refers to one of the debugging information
+&Refers to one of the debugging information
entries that \mbox{describe} the program. There are four types of
\mbox{reference}. The first is an offset relative to the beginning
of the \mbox{compilation} unit in which the reference occurs and must
the unit containing the reference. The third type of reference
is an indirect reference to a
\addtoindexx{type signature}
-type definition using a 8-byte \mbox{signature}
+type definition using
+\bb
+an
+\eb
+8-byte \mbox{signature}
for that type. The fourth type of reference is a reference from within the
\dotdebuginfo{} section of the executable or shared object file to
a debugging information entry in the \dotdebuginfo{} section of
\hypertarget{chap:classstring}{}
\livelinki{datarep:classstring}{string}{string class}
-& A null\dash terminated sequence of zero or more
-(non\dash null) bytes. Data in this class are generally
+& A null-terminated sequence of zero or more
+(non-null) bytes. Data in this class are generally
printable strings. Strings may be represented directly in
the debugging \mbox{information} entry or as an offset in a separate
string table.
\hypertarget{chap:classstroffsetsptr}{}
\livelinki{datarep:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class}
-&Refers to a base location in the DWARF section that holds
-a series of offsets in the DWARF section that holds strings.
-Certain attributes refer to one of these offsets by indexing
-\mbox{relative} to this base location. The resulting offset is then
+&
+\bb
+Specifies a
+\eb
+location in the DWARF section that holds
+a series of offsets
+\bb
+into
+\eb
+the DWARF section that holds strings.
+Certain attributes
+\bb
+use
+\eb
+one of these offsets by indexing
+\mbox{relative} to this location. The resulting offset is then
used to index into the DWARF string section.
\\
\addtoindexx{debugging information entry!ownership relation}
of debugging
information entries is achieved naturally because the debugging
-information is represented as a tree.
-The nodes of the tree
+information is represented as a tree. The nodes of the tree
are the debugging information entries themselves.
-The child
-entries of any node are exactly those debugging information
+The child entries of any node are exactly those debugging information
entries owned by that node.
\needlines{4}
The value of this attribute is a reference to the sibling entry
of the entry to which the attribute is attached.
-
-\section{Target Addressable Units and Addresses}
+\bb
+\section{Target Addresses}
\label{chap:targetaddressableunitsandaddresses}
-The standard assumes that the smallest directly
-\addtoindex{addressable unit} of memory on the
-target architecture is a byte consisting of eight bits.
-
\label{chap:targetaddresses}
-Many places in this document refer to the size of an
+\eb
+\addtoindexx{size of an address}
\addtoindexx{size of an address|see{\textit{also} \texttt{address\_size}}}
-\addtoindexi{address}{size of an address}
\addtoindexx{address size|see{size of an address}}
\addtoindexx{address size|see{\textit{also} \texttt{address\_size}}}
+Many places in this document refer to the size of an address
on the target architecture (or equivalently, target machine)
to which a DWARF description applies. For processors which
can be configured to have different address sizes or different
\addtoindexx{size of an address}
address sizes. In
that case, the DWARF debugging information contained in this
-object file will use the same address size.
-}
+object file will use the same address size.}
-\textit{%
-Architectures which have multiple instruction sets are
-supported by the \texttt{isa} entry in the line number information
-(see Section \refersec{chap:statemachineregisters}).
-}
+\bbpareb
\needlines{4}
\section{DWARF Expressions}
\label{chap:dwarfexpressions}
-DWARF expressions describe how to compute a value or name a
-location during debugging of a program.
+DWARF expressions describe how to compute a value or
+\bb
+specify a location.
+\eb
They are expressed in
terms of DWARF operations that operate on a stack of values.
-All DWARF operations are encoded as a stream of opcodes that
-are each followed by zero or more literal operands.
-The number
-of operands is determined by the opcode.
+\bb
+A DWARF expression is encoded as a stream of operations,
+each consisting of an opcode
+\eb
+followed by zero or more literal operands.
+The number of operands is
+\bb
+implied
+\eb
+by the opcode.
In addition to the
general operations that are defined here, operations that are
Each element of the stack has a type and a value, and can represent
a value of any supported base type of the target machine. Instead of
a base type, elements can have a
-\livetarg{chap:specialaddresstype}{special address type},
+\definitionx{special address type}\livetarg{chap:specialaddresstype}{},
which is an integral type that has the
\addtoindex{size of an address} on the target machine and
unspecified signedness. The value on the top of the stack after
value of the array bound, the length of a dynamic string,
the desired value itself, and so on).
-\needlines{4}
-\textit{While the abstract definition of the stack calls for variable-size entries
-able to hold any supported base type, in practice it is expected that each
-element of the stack can be represented as a fixed-size element large enough
-to hold a value of any type supported by the DWARF consumer for that target,
-plus a small identifier sufficient to encode the type of that element.
-Support for base types other than what is required to do address arithmetic
-is intended only for debugging of optimized code, and the completeness of the
-DWARF consumer's support for the full set of base types is a
-quality-of-implementation issue. If a consumer encounters a DWARF expression
-that uses a type it does not support, it should ignore the entire expression
-and report its inability to provide the requested information.}
-
-\textit{It should also be noted that floating-point arithmetic is highly dependent
-on the computational environment. It is not the intention of this expression
-evaluation facility to produce identical results to those produced by the
-program being debugged while executing on the target machine. Floating-point
-computations in this stack machine will be done with precision control and
-rounding modes as defined by the implementation.}
+\bbpareb
\needlines{4}
\subsubsection{Literal Encodings}
The single operand of a \DWOPconstnsNAME{} operation provides a 1,
2, 4, or 8-byte signed integer constant, respectively.
+\needlines{4}
\itembfnl{\DWOPconstuTARG}
The single operand of the \DWOPconstuNAME{} operation provides
an unsigned LEB128\addtoindexx{LEB128!unsigned} integer constant.
\DWTAGbasetype{} entry that provides the type of the constant provided. The
second operand is 1-byte unsigned integer that specifies the size of the
constant value, which is the same as the size of the base type referenced
-by the first operand. The third operand is a block of specified
-size that is to be interpreted as a value of the referenced type.
+by the first operand. The third operand is a
+\bb
+sequence of bytes of the given size that is
+\eb
+interpreted as a value of the referenced type.
\textit{While the size of the constant can be inferred from the base type
definition, it is encoded explicitly into the operation so that the
The \DWOPfbregNAME{} operation provides a
signed LEB128\addtoindexx{LEB128!signed} offset
from the address specified by the location description in the
-\DWATframebase{} attribute of the current function. (This
-is typically a \doublequote{stack pointer} register plus or minus
-some offset. On more sophisticated systems it might be a
-location list that adjusts the offset according to changes
-in the stack pointer as the PC changes.)
+\DWATframebase{} attribute of the current function.
+
+\bb
+\textit{This is typically a stack pointer register plus or minus some offset.}
+\eb
\itembfnl{\DWOPbregzeroTARG, \DWOPbregoneTARG, \dots, \DWOPbregthirtyoneTARG}
The single operand of the \DWOPbregnTARG{}
operations provides
a signed LEB128\addtoindexx{LEB128!signed} offset from
+\bb
+the contents of
+\eb
the specified register.
\itembfnl{\DWOPbregxTARG}
that index the stack assume that the top of the stack (most
recently added entry) has index 0.
-The \DWOPdup{}, \DWOPdrop{}, \DWOPpick{}, \DWOPover{}, \DWOPswap{}
-and \DWOProt{} operations manipulate the elements of the stack as pairs
-consisting of the value together with its type identifier.
-The \DWOPderef{}, \DWOPderefsize{}, \DWOPxderef{}, \DWOPxderefsize{}
-and \DWOPformtlsaddress{}
-operations require the popped values to have an integral type, either the
-\specialaddresstype{} or some other integral base type, and push a
-value with the \specialaddresstype.
-\DWOPdereftype{} and \DWOPxdereftype{} operations have the
-same requirement on the popped values, but push a value together
-with the same type as the popped values.
-All other operations push a value together with the \specialaddresstype.
+\bb
+Each entry on the stack has an associated type.
+\eb
\needlines{4}
\begin{enumerate}[1. ]
\itembfnl{\DWOPderefTARG}
The \DWOPderefNAME{} operation pops the top stack entry and
treats it as an address. The popped value must have an integral type.
-The value retrieved from that address is pushed, together with the
-\specialaddresstype{} identifier.
+The value retrieved from that address is pushed,
+\bb
+and has the \specialaddresstype{}.
+\eb
The size of the data retrieved from the
\addtoindexi{dereferenced}{address!dereference operator}
address is the \addtoindex{size of an address} on the target machine.
-\needlines{4}
+\needlines{6}
\itembfnl{\DWOPderefsizeTARG}
The \DWOPderefsizeNAME{} operation behaves like the
\DWOPderef{}
operation: it pops the top stack entry and treats it as an
address. The popped value must have an integral type.
-The value retrieved from that address is pushed, together with the
-\specialaddresstype{} identifier. In
-the \DWOPderefsizeNAME{} operation, however, the size in bytes
+The value retrieved from that address is pushed,
+\bb
+and has the \specialaddresstype{}.
+\eb
+In the \DWOPderefsizeNAME{} operation, however, the size in bytes
of the data retrieved from the dereferenced address is
specified by the single operand. This operand is a 1-byte
unsigned integral constant whose value may not be larger
\addtoindexi{dereferenced}{address!dereference operator}
address is the size of the \specialaddresstype.
+\needlines{4}
\itembfnl{\DWOPxderefsizeTARG}
The \DWOPxderefsizeNAME{} operation behaves like the
\DWOPxderef{} operation. The entry at the top of the stack is
\textit{Examples illustrating many of these stack operations are
found in Appendix \refersec{app:dwarfstackoperationexamples}.}
+\needlines{4}
\subsubsection{Arithmetic and Logical Operations}
\addtoindexx{DWARF expression!arithmetic operations}
\addtoindexx{DWARF expression!logical operations}
-The following provide arithmetic and logical operations. If an operation
-pops two values from the stack, both values must have the same type,
+The following provide arithmetic and logical operations.
+\bb
+Operands of an operation with two operands
+\eb
+must have the same type,
either the same base type or both the \specialaddresstype.
The result of the operation which is pushed back has the same type
-as the type of the operands.
+as the type of the operand(s).
If the type of the operands is the \specialaddresstype,
except as otherwise specified, the arithmetic operations
The \DWOPmulNAME{} operation pops the top two stack entries, multiplies them together, and
pushes the result.
+\needlines{4}
\itembfnl{\DWOPnegTARG}
The \DWOPnegNAME{} operation pops the top stack entry, interprets
it as a signed value and pushes its negation. If the negation
\itembfnl{\DWOPplusuconstTARG}
The \DWOPplusuconstNAME{} operation pops the top stack entry,
adds it to the unsigned LEB128\addtoindexx{LEB128!unsigned}
-constant operand and pushes the result.
+constant operand
+\bb
+interpreted as the same type as the operand popped from the
+top of the stack
+\eb
+and pushes the result.
\textit{This operation is supplied specifically to be
able to encode more field offsets in two bytes than can be
\itembfnl{\DWOPleTARG, \DWOPgeTARG, \DWOPeqTARG, \DWOPltTARG, \DWOPgtTARG, \DWOPneTARG}
The six relational operators each:
\begin{itemize}
-\item pop the top two stack values, which should both have the same type,
+\item pop the top two stack values, which \bb\eb have the same type,
either the same base type or both the \specialaddresstype,
\item compare the operands:
If the operands have the \specialaddresstype, the comparisons
are performed as signed operations.
-The six operators are \DWOPleNAME{} (less than or equal to), \DWOPgeNAME{}
-(greater than or equal to), \DWOPeqNAME{} (equal to), \DWOPltNAME{} (less
-than), \DWOPgtNAME{} (greater than) and \DWOPneNAME{} (not equal to).
\needlines{6}
\itembfnl{\DWOPskipTARG}
\DWOPcalltwo, \DWOPcallfour{} and \DWOPcallref{} is exactly like
that for \DWFORMreftwo, \DWFORMreffour{} and \DWFORMrefaddr,
respectively
-(see Section \refersec{datarep:attributeencodings}).
-}
+(see Section \refersec{datarep:attributeencodings}).}
-These operations transfer
-control of DWARF expression evaluation to
+These operations transfer control of DWARF expression evaluation to
\addtoindexx{location attribute}
the
\DWATlocation{}
description, \DWOPentryvalueNAME{} pushes the value that register had upon
entering the current subprogram. If the block contains a DWARF expression,
the DWARF expression is evaluated as if it has been evaluated upon entering
-the current subprogram. The DWARF expression should not assume any values
-being present on the DWARF stack initially and should result in exactly one
-value being pushed on the DWARF stack when completed. That value is the value
-being pushed by the \DWOPentryvalueNAME{} operation.
+the current subprogram. The DWARF expression
+\bb
+assumes no values are present on the DWARF stack initially and results
+\eb
+in exactly one
+value being pushed on the DWARF stack when completed.
+\bb\eb
\DWOPpushobjectaddress{} is not meaningful inside of this DWARF operation.
\end{enumerate}
-\needlines{5}
+\needlines{8}
\section{Location Descriptions}
\label{chap:locationdescriptions}
\textit{Debugging information
\livelink{chap:lexicalblock}{lexical block} that owns it,
and it does not move during its lifetime.
-Single location descriptions are of two kinds:
-\begin{enumerate}[a) ]
-\item Simple location descriptions, which describe the location
-\addtoindexx{location description!simple}
-of one contiguous piece (usually all) of an object. A simple
-location description may describe a location in addressable
-memory, or in a register, or the lack of a location (with or
-without a known value).
-
-\item Composite location descriptions, which describe an
-\addtoindexx{location description!composite}
-object in terms of pieces each of which may be contained in
-part of a register or stored in a memory location unrelated
-to other pieces.
-
-\end{enumerate}
+\bbpareb
\needlines{4}
\item \textit{Location lists}, which are used to
\addtoindexx{location list}
location list table).
-\needlines{8}
\subsection{Single Location Descriptions}
A single location description is either:
\begin{enumerate}[1. ]
describes the location of one piece of the object; each
composition operation describes which part of the object is
located there. Each simple location description that is a
-DWARF expression is evaluated independently of any others
-(as though on its own separate stack, if any).
+DWARF expression is evaluated independently of any others.
+\bb\eb
\end{enumerate}
simple location description consists of one
contiguous piece or all of an object or value.
+\bb
+\needlines{4}
+\subsubsubsection{Empty Location Descriptions}
+An \addtoindex{empty location description}
+consists of a DWARF expression
+\addtoindexx{location description!empty}
+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).
+\eb
\subsubsubsection{Memory Location Descriptions}
A
\addtoindexx{location description!memory}
memory location description
\addtoindexx{memory location description}
-consists of a non\dash empty DWARF
+consists of a non-empty DWARF
expression (see
-Section \refersec{chap:dwarfexpressions}
-), whose value is the address of
+Section \refersec{chap:dwarfexpressions}),
+whose value is the address of
a piece or all of an object or other entity in memory.
\subsubsubsection{Register Location Descriptions}
description of an object or a piece of an object.
}
-The following DWARF operations can be used to name a register.
-
+The following DWARF operations can be used to
+\bb
+specify a register location.
+\eb
\textit{Note that the register number represents a DWARF specific
mapping of numbers onto the actual registers of a given
or is computed from other locations and values in the program.
\begin{enumerate}[1. ]
\itembfnl{\DWOPimplicitvalueTARG}
-The \DWOPimplicitvalueNAME{}
-operation specifies an immediate value
+The \DWOPimplicitvalueNAME{} operation specifies an immediate value
using two operands: an unsigned LEB128\addtoindexx{LEB128!unsigned}
-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}.
+length, followed by a
+\bb
+sequence of bytes of the given length that contain the value.
+\eb
\itembfnl{\DWOPstackvalueTARG}
The \DWOPstackvalueNAME{}
\needlines{4}
\itembfnl{\DWOPimplicitpointerTARG}
+\bb
+\textit{An optimizing compiler may eliminate a pointer, while
+still retaining the value that the pointer addressed.
+\DWOPimplicitpointerNAME{} allows a producer to describe this value.}
+\eb
+
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
used to describe values that exist neither in memory nor in a
single register.}
-\needlines{4}
-\subsubsubsection{Empty Location Descriptions}
-An \addtoindex{empty location description}
-consists of a DWARF expression
-\addtoindexx{location description!empty}
-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).
+\bbpareb
\needlines{6}
\subsubsection{Composite Location Descriptions}
or store a variable partially in memory and partially in
registers. \DWOPpieceNAME{} provides a way of describing how large
a part of a variable a particular DWARF location description
-refers to. }
+refers to.}
+\needlines{4}
\itembfnl{\DWOPbitpieceTARG}
The \DWOPbitpieceNAME{}
operation takes two operands. The first
preceding DWARF location description.
Interpretation of the
-offset depends on the kind of location description. If the
+offset depends on the
+\bb\eb
+location description. If the
location description is empty, the offset doesn\textquoteright t matter and
the \DWOPbitpieceNAME{} operation describes a piece consisting
of the given number of bits whose values are undefined. If
(see Section \refersec{datarep:splitdwarfobjectfiles}). The two
forms are otherwise equivalent.
-\textit{The form for \splitDWARFobjectfile{s} is new in \DWARFVersionV.}
+\bbpareb
+\needlines{4}
\subsubsection{Location Lists in Non-split Objects}
\label{chap:locationlistsinnonsplitobjects}
Location lists
\item The value 0.
\item The value of the largest representable address offset (for
example, \wffffffff when the size of an address is 32 bits).
-\item A simple location description describing the location of the
+\item
+\bb
+An unsigned 2-byte length describing the length of the location
+ description that follows.
+\eb
+\item A \bb single \eb location description describing the location of the
object when there is no prior normal location list entry
that applies in the same location list.
\end{enumerate}
entry of a location list except for the terminating end-of-list
entry.
-A \addtoindex{default location list entry} describes a simple
+A \addtoindex{default location list entry} describes a \bb single \eb
location which applies to all addresses which are not included
in any range defined earlier in the same location list.
compilation unit base address. A single location
description follows the fields that define the address range.
+\needlines{5}
\itembfnl{\DWLLEstartlengthentryTARG}
This entry contains one unsigned LEB128\addtoindexx{LEB128!unsigned}
value and a 4-byte
The starting address given by this
type of entry is not relative to the compilation unit
base address. The second value is the
-length of the range. A single location
+length of the range
+\bb
+in bytes.
+\eb
+A single location
description follows the fields that define the address range.
\itembfnl{\DWLLEoffsetpairentryTARG}
\needlines{4}
\textit{The \DWLLEbaseaddressselectionentry, \DWLLEstartendentry{}
-and \DWLLEstartlengthentry entries obtain addresses within the
+and \DWLLEstartlengthentry{} entries obtain addresses within the
target program indirectly using an index (not an offset) into an
array of addresses. The base of that array is obtained using the
\DWATaddrbase{} attribute of the containing compilation unit.
Alternatively, the entry referenced may describe a type
modifier, such as constant, packed, pointer, reference or
volatile, which in turn will reference another entry describing
-a type or type modifier (using
-\addtoindexx{type attribute}
-a \DWATtypeNAME{} attribute of its
+a type or type modifier (using a
+\DWATtypeNAME{} attribute\addtoindexx{type attribute} of its
own). See
-Section \referfol{chap:typeentries}
+\bb
+Chapter
+\eb
+\referfol{chap:typeentries}
for descriptions of the entries describing
base types, user-defined types and type modifiers.
\textit{A compiler may wish to generate debugging information entries
for objects or types that were not actually declared in the
source of the application. An example is a formal parameter
-%FIXME: The word 'this' should be rendered like a variant italic,
-%FIXME: not as a quoted name. Changed to tt font--RB
entry to represent the hidden
\texttt{this} parameter\index{this parameter@\texttt{this} parameter}
that most \addtoindex{C++} implementations pass as the first argument
\hypertarget{chap:DWATdecllinelinenumberofsourcedeclaration}{}
representing
\hypertarget{chap:DWATdeclcolumncolumnpositionofsourcedeclaration}{}
-the
-\addtoindexx{line number of declaration}
-declaration of an object, module, subprogram or
-\addtoindex{declaration column attribute}
-type
-\addtoindex{declaration file attribute}
-may
-\addtoindex{declaration line attribute}
-have
-\DWATdeclfileDEFN,
-\DWATdecllineDEFN{} and
-\DWATdeclcolumnDEFN{}
-attributes each of whose value is an unsigned
+the declaration of an object, module, subprogram or type may have
+\DWATdeclfileDEFN,\addtoindexx{declaration file attribute}
+\DWATdecllineDEFN\addtoindexx{declaration line attribute} and
+\DWATdeclcolumnDEFN\addtoindexx{declaration column attribute}
+attributes, each of whose value is an unsigned
\livelink{chap:classconstant}{integer constant}.
The value of
a program entity that has been given a name may have a
\DWATnameDEFN{}
attribute\addtoindexx{name attribute}, whose value of
+\bb
+class
+\eb
\CLASSstring{} represents the name as it appears in
the source program. A debugging information entry containing
no name attribute, or containing a name attribute whose value
A
\addtoindex{DWARF procedure}
is represented by any
-kind of debugging information entry that has a
+\bb\eb
+debugging information entry that has a
\addtoindexx{location attribute}
\DWATlocationNAME{}
attribute.
In addition, a non-contiguous range of
addresses may also be specified for the
-\DWATstartscope{} attribute.
-\addtoindexx{start scope attribute}
+\DWATstartscope{} attribute\addtoindexx{start scope attribute}
+\bb
+(see Section \refersec{chap:dataobjectentries}).
+\eb
If an entity has no associated machine code,
none of these attributes are specified.
When there is a single address associated with an entity,
such as a label or alternate entry point of a subprogram,
the entry has a \DWATlowpc{} attribute whose value is the
-relocated address for the entity.
+\bb\eb address for the entity.
-\textit{While the \DWATentrypc{}
-attribute might also seem appropriate for this purpose,
-historically the \DWATlowpc{} attribute was used before
-\DWATentrypc{} was introduced
-(in \addtoindex{DWARF Version 3}). There is
-insufficient reason to change this;
-\DWATlowpc{} serves as a default entry PC address as described
-in Section \refersec{chap:entryaddress}.}
+\bbpareb
\needlines{8}
-\subsection{Continuous Address Range}
+\bb
+\subsection{Contiguous Address Range}
+\eb
\label{chap:contiguousaddressranges}
When the set of addresses of a debugging information entry can
be described as a single contiguous range, the entry
\addtoindexx{high PC attribute}
may
\addtoindexx{low PC attribute}
-have
-a \DWATlowpc{} and
-\DWAThighpc{} pair of attributes.
-The value
-of the
-\DWATlowpc{} attribute
-is the relocated address of the
+have a \DWATlowpc{} and \DWAThighpc{} pair of attributes.
+The value of the \DWATlowpc{} attribute is the \bb\eb address of the
first instruction associated with the entity. If the value of
-the \DWAThighpc{} is of class address, it is the relocated
+the \DWAThighpc{} is of class address, it is the \bb\eb
address of the first location past the last instruction
associated with the entity; if it is of class constant, the
value is an unsigned integer offset which when added to the
The presence of low and high PC attributes for an entity
implies that the code generated for the entity is contiguous
and exists totally within the boundaries specified by those
-two attributes. If that is not the case, no low and high PC
-attributes should be produced.
+two attributes.
+\bb\eb
\subsection{Non-Contiguous Address Ranges}
\label{chap:noncontiguousaddressranges}
When the set of addresses of a debugging information entry
\addtoindexx{non-contiguous address ranges}
-cannot be described as a single contiguous range, the entry has
-a \DWATranges{} attribute
-\addtoindexx{ranges attribute}
+cannot be described as a single contiguous range, the entry
+\bb
+may have
+\eb
+a \DWATranges{} attribute\addtoindexx{ranges attribute}
whose value is of class \livelink{chap:classrangelistptr}{rangelistptr}
and indicates the beginning of a \addtoindex{range list}.
Similarly,
-a \DWATstartscope{} attribute
-\addtoindexx{start scope attribute}
+a \DWATstartscope{} attribute\addtoindexx{start scope attribute}
+\bb
+(see Section \refersec{chap:dataobjectentries}).
+\eb
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
-\dotdebugranges{}. A
-\addtoindex{range list} is indicated by a
-\DWATranges{} attribute whose
-\addtoindexx{ranges attribute}
-value is represented as an offset from the beginning of the
+Range lists are contained in
+\bb
+the \dotdebugranges{} section.
+\eb
+A \addtoindex{range list} is indicated by a
+\DWATranges{} attribute\addtoindexx{ranges attribute}
+whose value is
+\bb\eb
+an offset from the beginning of the
\dotdebugranges{} section to the beginning of the
\addtoindex{range list}.
unit. The offset given by the \DWATranges{} attribute is
relative to that base.
-\textit{The \DWATrangesbase{} attribute is new in \DWARFVersionV.
-The advantage of this attribute is that it reduces the number of
-object language relocations needed for references to the \dotdebugranges{}
-section from one for each range entry to a single relocation that
-applies for the entire compilation unit.}
+\bbpareb
The \addtoindex{applicable base address} of a \addtoindex{range list}
entry is determined
\end{enumerate}
\textit{A base address selection entry affects only the
-remainder of list in which it is contained.}
+remainder of
+\bb
+the
+\eb
+list in which it is contained.}
\subsubsection{End-of-List Entry}
The end of any given \addtoindex{range list} is marked by an
\livelink{chap:tryandcatchblockentries}{try/catch \nolink{blocks}},
and the like, may have a \DWATentrypcDEFN{} attribute
\addtoindexx{entry PC address}
-to indicate the first executable instruction within that
+to indicate the
+\bb
+instruction where execution should begin
+\eb
+within that
range\hypertarget{chap:entryaddressofscope}{}
-of addresses. The value of the \DWATentrypcNAME{} attribute is a
-relocated address if the
-value of \DWATentrypcNAME{} is of class \CLASSaddress; or if it is of class
+of addresses.
+\bb
+If the value of the \DWATentrypcNAME{} attribute is of
+class \CLASSaddress{} that address is the entry address;
+or,
+\eb
+if it is of class
\CLASSconstant, the value is an unsigned integer offset which, when
added to the base address of the function, gives the entry
address.
The value of these
attributes is determined based on the class as follows:
\begin{itemize}
-\item For a \livelink{chap:classconstant}{constant}, the value of the constant is the value of
-the attribute.
+\item For a \livelink{chap:classconstant}{constant}, the value
+of the constant is the value of the attribute.
\item For a \livelink{chap:classreference}{reference}, the
-value is a reference to another DIE. This DIE may:
+value is a reference to another
+\bb
+debugging information entry. This entry may:
+\eb
\begin{itemize}
\renewcommand{\itemsep}{0cm}
\item describe a constant which is the attribute value,
\item describe a variable which contains the attribute value, or
-\item contain a DWARF expression which computes the attribute value
- (for example, be a \DWTAGdwarfprocedure{} entry).
+\item
+\bb
+ contain a \DWATlocation{} attribute whose value is a \eb
+ DWARF expression which computes the attribute value
+ (for example, \bb\eb a \DWTAGdwarfprocedure{} entry).
\end{itemize}
-\item For an \livelink{chap:classexprloc}{exprloc}, the value is interpreted as a
-DWARF expression;
-evaluation of the expression yields the value of
-the attribute.
+\item For an \livelink{chap:classexprloc}{exprloc}, the value
+is interpreted as a DWARF expression; evaluation of the expression
+yields the value of the attribute.
\end{itemize}
-\textit{Whether an attribute value can be dynamic depends on the
-rules of the applicable programming language.
-}
+\bbpareb
\needlines{4}
\section{Entity Descriptions}
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
-\addtoindexx{linkage name attribute}
-\DWATlinkagenameDEFN{}
-attribute whose value is a null-terminated string containing the
+\DWATlinkagenameDEFN{}\hypertarget{chap:DWATlinkagenameobjectfilelinkagenameofanentity}{}
+attribute\addtoindexx{linkage name attribute}
+whose value is a null-terminated string containing the
object file linkage name associated with the corresponding entity.
\livetarg{chap:DWATalignmentnondefault}{}
A debugging information entry may have a
\DWATalignmentDEFN{} attribute\addtoindexx{alignment attribute}
-that describes the (non-default) alignment requirements of the entry.
-\DWATalignment{} has a positive, non-zero, integer constant value
-describing the strictest specified (non-default) alignment of the entity.
-This constant describes the actual alignment used by the compiler.
-(If there are multiple alignments specified by the user, or if the
-user specified an alignment the compiler could not satisfy, then
-only the strictest alignment is added using this attribute.)
+\bb
+whose value of class \CLASSconstant{} is
+a positive, non-zero, integer describing the
+\eb
+alignment of the entity.
+\bb\eb
\textit{For example, an alignment attribute whose value is 8 indicates
that the entity to which it applies occurs at an address that is a
way the debugging information is encoded and represented in
an object file.
-The informational content is described in
-Sections \ref{chap:generaldescription}
+The informational content is described in
+\bb
+Chapters
+\eb
+\ref{chap:generaldescription}
through
\ref{chap:otherdebugginginformation}.
-Section \ref{chap:generaldescription}
+Chapter \ref{chap:generaldescription}
describes the overall structure of the information
-and attributes that is common to many or all of the different
+and attributes that are common to many or all of the different
debugging information entries.
-Sections \ref{chap:programscopeentries},
+\bb
+Chapters
+\eb \ref{chap:programscopeentries},
\ref{chap:dataobjectandobjectlistentries} and
\ref{chap:typeentries} describe
the specific debugging information entries and how they
communicate the necessary information about the source program
to a debugger.
-Section \ref{chap:otherdebugginginformation}
+\bb
+Chapter
+\eb
+\ref{chap:otherdebugginginformation}
describes debugging information
contained outside of the debugging information entries. The
encoding of the DWARF information is presented in
-Section \ref{datarep:datarepresentation}.
+\bb
+Chapter
+\eb
+\ref{datarep:datarepresentation}.
This organization closely follows that used in the
\DWARFVersionIV{} document. Except where needed to incorporate
of explanatory or supplementary material, and are not part
of the formal definition.
-\bb
\section{Objectives and Rationale}
DWARF has had a set of objectives since its inception which have
Although DWARF Version 1 was developed in the late 1980's as a
format to support debugging C programs written for AT\&T hardware
running SVR4, \DWARFVersionII{} and later has evolved far beyond
-this origin. One difference between DWARF and other object formats
+this origin. One difference between DWARF and other
+\bb\eb
+formats
is that the latter are often specific to a particular language,
architecture, and/or operating system.
general application. For these, DWARF has a description
designed to meet the language requirements, although, to the
extent possible, an effort is made to generalize the attribute.
-An example of this is the \DWTAGconditionNAME{} DIE, which is
+An example of this is the \DWTAGconditionNAME{} DIE,
+\bb\eb
used to describe \addtoindex{COBOL} level 88 conditions, which
is described in abstract terms rather than COBOL-specific terms.
Conceivably, this TAG might be used with a different language
organization of the ELF object file format. Nonetheless, DWARF
attempts to be independent of either the OS or the object file
format. There have been implementations of DWARF debugging
-data in OMF or COFF object files.
+data in
+\bb
+COFF, Mach-O and other object file formats.
+\eb
DWARF assumes that any object file format will be able to
distinguish the various DWARF data sections in some fashion,
DWARF makes a few assumptions about functionality provided by
the underlying operating system. DWARF data sections can be
-read sequentially and independently, for example, to read the
-\dotdebugabbrev{} section before the \dotdebuginfo{} section.
-Each DWARF data section is a sequential sequence of 8-bit bytes,
+read sequentially and independently.
+\bb\eb
+Each DWARF data section is a \bb\eb sequence of 8-bit bytes,
numbered starting with zero. The presence of offsets from one
DWARF data section into other data sections does not imply that
the underlying OS must be able to position files randomly; a
\subsection{Compact Data Representation}
The DWARF description is designed to be a compact file-oriented
-representation. In most cases, it is anticipated that DWARF
-debug data will be read by a consumer (usually a debugger) and
-onverted into a more efficiently accessed internal representation.
-For the most part, the DWARF data in a section is not the same as
-this internal representation.
+representation.\bb\eb
There are several encodings which achieve this goal, such as the
TAG and attribute abbreviations or the line number encoding.
the executable, or the type units, which allow similar type
definitions from multiple compilations to be combined.
-There is a tension between this objective and the following
-objective. Every compaction scheme results in more processing
-which needs to be performed to process the DWARF debug data.
+\bb
+In most cases, it is anticipated that DWARF
+debug data will be read by a consumer (usually a debugger) and
+converted into a more efficiently accessed internal representation.
+For the most part, the DWARF data in a section is not the same as
+this internal representation.
+\eb
\subsection{Efficient Processing}
DWARF is designed to be processed efficiently, so that a
DWARF attempts to allow developers the greatest flexibility
in designing implementations, without mandating any particular
design decisions. Issues which can be described as
-\doublequote{Quality of Implementation} are avoided.
+\bb
+quality-of-implementation
+\eb
+are avoided.
-\subsection{Explicit rather than Implicit Description}
+\bb
+\subsection{Explicit Rather Than Implicit Description}
+\eb
DWARF describes the source to object translation explicitly
rather than using common practice or convention as an implicit
understanding between producer and consumer. For example, where
rather than repeating the same information multiple times. The
string sections can be compacted to eliminate duplicate strings,
for example. Other compaction schemes or references between
-ections support this. Whether a particular implementation is
+\bb
+sections
+\eb
+support this. Whether a particular implementation is
effective at eliminating duplicate data, or even attempts to,
-is a Quality of Implementation issue.
+is a
+\bb
+quality-of-implementation
+\eb
+issue.
\subsection{Leverage Other Standards}
Where another standard exists which describes how to interpret
aspects of a program, DWARF defers to that standard rather than
attempting to duplicate the description. For example, C++ has
-pecific rules for deciding which function to call depending
+\bb
+specific
+\eb
+rules for deciding which function to call depending
name, scope, argument types, and other factors. DWARF describes
the functions and arguments, but doesn't attempt to describe
how one would be selected by a consumer performing any particular
support DWARF data. This may require the implementer to be
careful that they do not generate DWARF data which cannot be
processed by these programs. Conversely, an assembler which
-can generate LEB128 values may allow the compiler to generate
+can generate LEB128
+\bb
+(Little-Endian Base 128)
+\eb
+values may allow the compiler to generate
more compact descriptions, and a linker which understands the
format of string sections can merge these sections. Whether
-or not an implementation includes these functions is a Quality
-of Implementation issue, not mandated by the DWARF specification.
+or not an implementation includes these functions is a
+\bb
+quality-of-implementation
+\eb
+issue, not mandated by the DWARF specification.
-\subsection{Separate Description from Implementation}
+\subsection{Separate Description From Implementation}
DWARF intends to describe the translation of a program from
source to object, while neither mandating any particular design
nor making any other design difficult. For example, DWARF
are to be described, but doesn't specify how this data is
collected or organized by a producer. Where a particular DWARF
feature anticipates that it will be implemented in a certain
-fashion, non-normative text will suggest but not require this design.
+fashion,
+\bb
+informative
+\eb
+text will suggest but not require this design.
-\subsection{Permissive rather than Prescriptive}
+\bb
+\subsection{Permissive Rather Than Prescriptive}
+\eb
The DWARF Standard specifies the meaning of DWARF descriptions.
It does not specify what a particular producer should generate
for any source to object conversion, nor what a particular
for the same source to object conversion. As long as the DWARF
description follows this specification, the producer is
generating valid DWARF.
-For example, DWARF allows producers to identify the end of a
+For example, DWARF allows
+\bb
+a producer
+\eb
+to identify the end of a
function prologue in the Line Information so that a debugger
can stop at this location. A producer which does this is
generating valid DWARF, as is another which doesn't.
\subsection{Vendor Extensibility}
-\eb
This document does not attempt to cover all interesting
languages or even to cover all of the possible debugging
information needs for its primary target languages.
names and values not reserved for vendor additions, however,
are reserved for future versions of this document.
-\bb
Where this specification provides a means for
-\eb
describing the source language, implementors are expected
to adhere to that specification.
For language features that
version of this standard or which contain vendor extensions,
albeit possibly in a degraded manner.
-\section{Changes from Version 4 to Version 5}
+\bb
+\section{Changes From Version 4 to Version 5}
+\eb
\addtoindexx{DWARF Version 5}
The following is a list of the major changes made to the DWARF Debugging Information
Format since Version 4 was published. The list is not meant to be exhaustive.
\item The \dotdebugtypes{}
%\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
section introduced in \DWARFVersionIV{}
-is eliminated and its contents instead contained in \dotdebuginfo{} sections
-to facilitate other changes.
-\item Add support for collecting common DWARF information (DIEs and macro definitions)
+is eliminated and its contents instead contained in \dotdebuginfo{} sections.
+\bb\eb
+\item Add support for collecting common DWARF information
+\bb
+(debugging information entries
+\eb
+and macro definitions)
across multiple executable and shared files and keeping it in a single
\addtoindex{supplementary object file}.
-\item A new line number program header design provides the ability to
-use an MD5 hash to validate source file version in use, allows pooling
+\item A new line number program header
+\bb
+format
+\eb
+provides the ability to
+use an MD5 hash to validate
+\bb
+the
+\eb
+source file version in use, allows pooling
of directory and file name strings and makes provision for vendor-defined
extensions. It also adds a string section specific to the line number table
(\dotdebuglinestr)
except for line number information.
\needlines{4}
\item Add a split object file and package representations to allow most
-DWARF information to be compacted and/or kept separate from an executable
+DWARF information to be
+\bb\eb
+kept separate from an executable
or shared image. This includes new sections
\dotdebugaddr, \dotdebugstroffsets, \dotdebugabbrevdwo, \dotdebuginfodwo,
\dotdebuglinedwo, \dotdebuglocdwo, \dotdebugmacrodwo, \dotdebugstrdwo,
\dotdebugstroffsetsdwo, \dotdebugcuindex{} and \dotdebugtuindex{}
together with new forms of attribute value for referencing these sections.
-This enhances DWARF support for very large programs by saving space
-and improving link times.
+This enhances DWARF support
+\bb
+by reducing executable program size and
+by improving link times.
+\eb
\item Replace the \dotdebugmacinfo{} macro information representation with
-a much more compact \dotdebugmacro{} representation.
+\bb
+with a \dotdebugmacro{} representation that can potentially be much more compact.
+\eb
\item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
with a single and more functional name index section, \dotdebugnames{}.
-\item Add a new debugging information entry (\DWTAGcallsiteNAME) and related
+\item Add a new debugging information entry (\DWTAGcallsiteNAME), related
+\bb\eb
attributes and DWARF expression operators to describe call site information,
including identification of tail calls and tail recursion.
-This facilitates debugging of optimized code.
+\bb\eb
\item Add improved support for \addtoindex{FORTRAN} assumed rank arrays
(\DWTAGgenericsubrangeNAME), dynamic rank arrays (\DWATrankNAME)
and co-arrays (\DWTAGcoarraytypeNAME{}).
-\item Add a new option to allow debuggers and other DWARF consumers to
-support a DWARF expression stack containing typed values.
-\item Add improved support for the \addtoindex{C++} \texttt{auto}
-return type, deleted member functions (\DWATdeletedNAME), as well as defaulted
-constructors and destructors (\DWATdefaultedNAME).
-\item Add a new attribute, \DWATnoreturnNAME{}, to identify
+\item Add
+\bb
+new operations that allow support for
+\eb
+a DWARF expression stack containing typed values.
+\item Add improved support for the \addtoindex{C++}:
+\bb\eb
+\texttt{auto} return type, deleted member functions (\DWATdeletedNAME),
+as well as defaulted constructors and destructors (\DWATdefaultedNAME).
+\item Add a new attribute
+\bb
+(\DWATnoreturnNAME{}),
+\eb
+to identify
a subprogram that does not return to its caller.
\item Add language codes for C 2011, C++ 2003, C++ 2011, C++ 2014,
Dylan, Fortran 2003, Fortran 2008, Go, Haskell,
-Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
+Julia, Modula 3, Ocaml,
+\bb
+OpenCL, Rust
+\eb
+and Swift.
\item Numerous other more minor additions to improve functionality
and performance.
\end{itemize}
a new \HFNunittype{} field.
\needlines{4}
\item New operand forms for attribute values are defined
-(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME,
+(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME,
+\bb
+\DWFORMimplicitconstNAME,
+\eb
+\DWFORMlinestrpNAME,
\DWFORMrefsupNAME, \DWFORMstrpsupNAME{} and \DWFORMstrxNAME).
-(Because a pre-DWARF Version 5 consumer will not be able to interpret
-these even to ignore and skip over them, such new forms must be
-considered incompatible.)
-\item The line number table header (in the \dotdebugline{} section)
+
+\textit{Because a pre-DWARF Version 5 consumer will not be able to interpret
+these even to ignore and skip over them, new forms must be
+considered incompatible additions.}
+\item The line number table header
+\bb\eb
is substantially revised.
\needlines{4}
-\item A location list entry (see Section \refersec{chap:locationlists})
+\item A location list entry
+\bb\eb
with the address range \mbox{(0, \textit{maximum-address})} is defined
as the new default location list entry.
-\item In a string type (see Section \refersec{chap:stringtypeentries}),
-a \DWATbytesizeNAME{} attribute is defined to always describe the size
-of the string type. (Previously
-it described the size of the optional string length data field if the
-\DWATstringlengthNAME{} attribute was present.)
+\item In a string type,
+\bb
+the \DWATbytesizeNAME{} attribute is re-defined
+\eb
+to always describe the size of the string type.
+(Previously it described the size of the optional string length data
+field if the \DWATstringlengthNAME{} attribute was
+\bb
+also
+\eb
+present.)
\end{itemize}
While not strictly an incompatibility, the macro information
DWARF Git Projects / dwarf-doc.git / commitdiff