&\livelink{chap:DWATpicturestring}{DW\-\_AT\-\_picture\-\_string} \\
&\livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} \\
&\livelink{chap:DWATsmall}{DW\-\_AT\-\_small} \\
+\\
\hline
\livelink{chap:DWTAGcatchblock}{DW\-\_TAG\-\_catch\-\_block}
&\livelink{chap:DWATname}{DW\-\_AT\-\_name} \\
&\livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} \\
&\livelink{chap:DWATtype}{DW\-\_AT\-\_type} \\
+\\
+\\
\hline
\livelink{chap:DWTAGtemplatevalueparameter}{DW\-\_TAG\-\_template\-\_value\-\_parameter}
&\livelink{chap:DWATname}{DW\-\_AT\-\_name} \\
&\livelink{chap:DWATsibling}{DW\-\_AT\-\_sibling} \\
&\livelink{chap:DWATtype}{DW\-\_AT\-\_type} \\
+\\
\hline
\livelink{chap:DWTAGwithstmt}{DW\-\_TAG\-\_with\-\_stmt}
of section contributions must be retained or discarded as a
whole; no partial elimination is allowed. Section groups can
generally be handled by a linker in two ways:
+\begin{enumerate}[1. ]
-\begin{enumerate}[1.]
\item Given multiple identical (duplicate) section groups,
\addtoindexx{section group}
one of them is chosen to be kept and used, while the rest
What is minimally needed from the object file format and system
linker (outside of DWARF itself, and normal object/linker
facilities such as simple relocations) are:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item A means of referencing from inside one \addtoindex{.debug\_info}
compilation unit to another
\setlength{\parindent}{0pt}
\nonzeroparskip
-\dwf, Version 4.1 (Draft)
+\begin{center}
+\dwf, Version 4.1
-Copyright \copyright 2010, 2013 \dwf\ Committee
+Copyright\copyright 2010, 2013 \dwf\ Committee
+\end{center}
+\vspace{4ex}
Permission is granted to copy,
distribute and/or modify this document under the terms of the
GNU Free Documentation License, Version 1.3; with no
The debugging information entry for a program variable,
formal parameter or constant may have the following attributes:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item A \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute,
\addtoindexx{name attribute}
whose value is a null-terminated
object is smaller than (that is, is a subset of the addresses
of) the scope most closely enclosing the object. There are
two cases:
-\begin{enumerate}[a)]
+\begin{enumerate}[a) ]
\item If the scope of the object entry includes all of the
containing scope except for a contiguous sequence of bytes at
the beginning of that containing scope, then the scope of the
To ensure that extensions added by one vendor may be safely
ignored by consumers that do not understand those extensions,
the following rules should be followed:
+\begin{enumerate}[1. ]
-\begin{enumerate}[1.]
\item New attributes should be added in such a way that a
debugger may recognize the format of a new attribute value
without knowing the content of that attribute value.
The differences between the 32\dash\ and 64\dash bit
DWARF formats are
detailed in the following:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
+
\item In the 32\dash bit DWARF format, an
\addtoindex{initial length field}
(see
\subsubsection{Compilation Unit Header}
\label{datarep:compilationunitheader}
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item unit\_length (initial length) \\
\addtoindexx{unit\_length}
placed in its own \addtoindex{type unit}, within the
\addtoindex{.debug\_types} section,
consists of the following information:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item unit\_length (initial length) \\
\addtoindexx{unit\_length}
in the \addtoindex{.debug\_pubnames} and
\addtoindex{.debug\_pubtypes} sections begins
with a header consisting of:
+\begin{enumerate}[1. ]
-
-\begin{enumerate}[1.]
\item unit\_length (initial length) \\
\addtoindexx{unit\_length}
A 4\dash byte or 12\dash byte unsigned integer
Each set of entries in the table of address ranges contained
in the \addtoindex{.debug\_aranges}
section begins with a header containing:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
% FIXME The unit length text is not fully consistent across
% these tables.
of a flattened description of the type. The flattened
description of the type is a byte sequence derived from the
DWARF encoding of the type as follows:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item Start with an empty sequence S and a list V of visited
types, where V is initialized to a list containing the type
Steps 6 and 7 can themselves each be considered for a separate
\addtoindex{type unit}.}
+\needlines{4}
Where the DWARF producer may reasonably choose two or more
different forms for a given attribute, it should choose
the simplest possible form in computing the signature. (For
% If draft is in the document class list, pix are just suggested
% by an outline, the pic does not appear as a picture.
%
+\newcommand{\docdate}{10 February 2013 (***Draft***)}
+%
\usepackage{url} % For color in letters. Links instead?
\usepackage{color} % For color in letters. Links instead?
\usepackage{ellipsis} % Provides ... as \dots
\renewcommand{\familydefault}{phv} % font family helvetica
-\newcommand{\docdate}{7 February 2013}
-
\newcommand{\dwf}{DWARF Debugging Information Format}
\newenvironment{myindentpara}[1]%
% And description lists with normal (not bold) text
\renewcommand{\descriptionlabel}[1]{\hspace{\labelsep}\textnormal{#1}}
+\newcommand{\descriptionlabelnl}[1]{\item[#1] \mbox{}\\}
% Reduce vertical space at beginning of a list
\setlength{\topsep}{0in}
\newpage
Finally, the following notation is useful:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item sizeof(type): size in bytes of entities of the given type
\item offset(type, comp): offset in bytes of the comp component
within an entity of the given type
\end{lstlisting}
Interpretation of this expression proceeds as follows:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item Lookup name arrays. We find that it is a variable,
whose type is given by the unnamed type at 6\$. Notice that
\item Find the 5$^{th}$ element of that array object. To do array
indexing requires several pieces of information:
-
-\begin{enumerate}[a)]
+\begin{enumerate}[a) ]
\item the address of the array data
\item Find the second element of the array object found in step 3. To do array indexing requires
several pieces of information:
-
-\begin{enumerate}[a)]
+\begin{enumerate}[a) ]
\item the address of the array storage
\item the lower bounds of the array \\
% Using plain [] here gives trouble.
\lbrack To check that 2 is within bounds we would require the upper
-%bound too, but we\textquoteright ll skip that for this example \rbrack
+bound too, but we will skip that for this example \rbrack
\item the stride
Interesting aspects about this example are:
-
-\begin{enumerate}[1)]
+\begin{enumerate}[1. ]
\item The array VEC2 is ``immediately'' contained within structure
REC2 (there is no intermediate descriptor or indirection),
which is reflected in the absence of a \livelink{chap:DWATdatalocation}{DW\-\_AT\-\_data\-\_location}
approaches considered here.)
The approaches are:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item Inline both OUTER and INNER in all cases
\item Inline OUTER, multiple INNERs \\
&\livelinki{chap:DWATbitoffsetdatamemberbitlocation}{Data member bit location}{data member bit location} \\
\livetarg{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}
&\livelinki{chap:DWATbitsizebasetypebitsize}{Base type bit size}{base type bit size} \\
-&\livelink{chap:DWATbitsizedatamemberbitsize}{Data member bit size}{data member bit size} \\
+&\livelinki{chap:DWATbitsizedatamemberbitsize}{Data member bit size}{data member bit size} \\
\livetarg{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}
&\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)} \\
for the member function.}
Each set begins with a header containing four values:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item unit\_length (initial length) \\
\addtoindexx{unit\_length}
a single compilation unit.
Each set begins with a header containing five values:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item unit\_length (initial length) \\
\addtoindexx{unit\_length}
The total length of all of the
\subsection{Line Number Program Instructions}
The state machine instructions in a line number program belong to one of three categories:
-\begin{description}
-\item[special opcodes]
-
+\begin{enumerate}[1. ]
+\item special opcodes \\
These have a \addtoindex{ubyte} opcode field and no operands.\vspace{1ex}
\textit{Most of the instructions in a
-line number program are special opcodes.} \\
-
-\item[standard opcodes]
+line number program are special opcodes.}
+\item standard opcodes \\
These have a \addtoindex{ubyte} opcode field which may be followed by zero or more
\addtoindex{LEB128} operands (except for
\mbox{\livelink{chap:DWLNSfixedadvancepc}{DW\-\_LNS\-\_fixed\-\_advance\-\_pc},} see below).
The opcode implies the number of operands and their meanings, but the
line number program header also specifies the number of operands for
-each standard opcode. \\
-
-\item[extended opcodes]
+each standard opcode.
+\item extended opcodes \\
These have a multiple byte format. The first byte is zero; the next bytes
are an unsigned LEB128\addtoindexx{LEB128!unsigned} integer giving the number of bytes in the
instruction itself (does not include the first zero byte or the size). The
remaining bytes are the instruction itself (which begins with a \addtoindex{ubyte}
extended opcode). \\
-\end{description}
+\end{enumerate}
\subsection{The Line Number Program Header}
The line number program for each compilation unit begins with
a header containing the following fields in order:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item unit\_length (initial length) \\
\addtoindexx{unit\_length}
The size in bytes of the line number information for this
architectures, this field is 1, the \addtoindex{op\_index register} is always
0, and the operation pointer is simply the address register.
+\needlines{4}
\item default\_is\_stmt (\addtoindex{ubyte}) \\
\addtoindexx{default\_is\_stmt}
The initial value of the \addtoindex{is\_stmt} register.
\label{chap:specialopcodes}
Each \addtoindex{ubyte} special opcode has the following effect on the state machine:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item Add a signed integer to the line register.
of opcodes available) when the difference between addresses
is within the range [0, 20], but not all line advances are
available for the maximum \addtoindex{operation advance} (see below).}
-\textit{The opcode mapping would be:}
+
+\textit{The resulting opcode mapping is shown in
+Figure \refersec{fig:examplelinenumberspecialopcodemapping}.}
+
+\begin{figure}[ht]
\begin{alltt}\textit{
Line Advance
Operation
19 241 242 243 244 245 246 247 248 249 250 251 252
20 253 254 255
}\end{alltt}
-
+\caption{Example line number special opcode mapping}
+\label{fig:examplelinenumberspecialopcodemapping}
+\end{figure}
\textit{There is no requirement that the expression
255 - \addtoindex{line\_base} + 1 be an integral multiple of
The standard opcodes, their applicable operands and the
actions performed by these opcodes are as follows:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item \textbf{DW\-\_LNS\-\_copy} \\
The \livetarg{chap:DWLNScopy}{DW\-\_LNS\-\_copy}
single unsigned LEB128\addtoindexx{LEB128!unsigned} operand and stores it in the column
register of the state machine.
+\needlines{4}
\item \textbf{DW\-\_LNS\-\_negate\-\_stmt} \\
The \livetarg{chap:DWLNSnegatestmt}{DW\-\_LNS\-\_negate\-\_stmt} opcode takes no
operands. It sets the \addtoindex{is\_stmt} register of the state machine
to the logical negation of its current value.
+\needlines{4}
\item \textbf{DW\-\_LNS\-\_set\-\_basic\-\_block} \\
The \livetarg{chap:DWLNSsetbasicblock}{DW\-\_LNS\-\_set\-\_basic\-\_block}
opcode
The extended opcodes are as follows:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item \textbf{DW\-\_LNE\-\_end\-\_sequence} \\
The \livetarg{chap:DWLNEendsequence}{DW\-\_LNE\-\_end\-\_sequence} opcode takes no operands. It sets the
instruction which creates a row whose address is that of the
byte after the last target machine instruction of the sequence.
+\needlines{5}
\item \textbf{DW\-\_LNE\-\_set\-\_address} \\
The \livetarg{chap:DWLNEsetaddress}{DW\-\_LNE\-\_set\-\_address} opcode takes a single relocatable
address as an operand. The size of the operand is the size
\item \textbf{DW\-\_LNE\-\_define\-\_file} \\
The \livetarg{chap:DWLNEdefinefile}{DW\-\_LNE\-\_define\-\_file} opcode takes four operands:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item A null\dash terminated string containing the full or relative
path name of a source file. If the entry contains a file
integer. It sets the
\addtoindex{discriminator} register to the new value.
-
-
\end{enumerate}
\textit{Appendix \refersec{app:linenumberprogramexample}
user on the command line.
-
+\needlines{6}
\section{Call Frame Information}
\label{chap:callframeinformation}
-
-
-
\textit{Debuggers often need to be able to view and modify the state of any subroutine activation that is
\addtoindexx{activation!call frame}
on the call stack. An activation consists of:}
among many Frame Description Entries. There is at least one
CIE in every non-empty \addtoindex{.debug\_frame} section. A CIE contains
the following fields, in order:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item length (initial length) \\
A constant that gives the number of bytes of the CIE structure,
not including the length field itself
use it, in bytes.
\item \addtoindex{code\_alignment\_factor} (unsigned LEB128)
-\addtoindexx{LEB128!unsigned}\addtoindexx{unsigned LEB128|see{LEB128, unsigned}} \\
-\addtoindex{code alignment factor}
+\addtoindexx{LEB128!unsigned}\addtoindexx{unsigned LEB128|see{LEB128, unsigned}}
+\addtoindexx{code alignment factor} \\
A
\addtoindexx{\textless caf\textgreater|see{code alignment factor}}
constant that is factored out of all advance location
\end{enumerate}
An FDE contains the following fields, in order:
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item length (initial length) \\
A constant that gives the number of bytes of the header and
\item instructions (array of \addtoindex{ubyte}) \\
A sequence of table defining instructions that are described below.
-\item 6. padding (array of \addtoindex{ubyte}) \\
+\item padding (array of \addtoindex{ubyte}) \\
Enough \livelink{chap:DWCFAnop}{DW\-\_CFA\-\_nop} instructions
to make the size of this entry match the length value above.
\end{enumerate}
\subsubsection{Row Creation Instructions}
\label{chap:rowcreationinstructions}
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item \textbf{DW\-\_CFA\-\_set\-\_loc} \\
The \livetarg{chap:DWCFAsetloc}{DW\-\_CFA\-\_set\-\_loc} instruction
\subsubsection{CFA Definition Instructions}
\label{chap:cfadefinitioninstructions}
+\begin{enumerate}[1. ]
-\begin{enumerate}[1.]
\item \textbf{DW\-\_CFA\-\_def\-\_cfa} \\
The \livetarg{chap:DWCFAdefcfa}{DW\-\_CFA\-\_def\-\_cfa}
instruction takes two unsigned LEB128\addtoindexx{LEB128!unsigned}
\subsubsection{Register Rule Instructions}
\label{chap:registerruleinstructions}
+\begin{enumerate}[1. ]
-\begin{enumerate}[1.]
\item \textbf{DW\-\_CFA\-\_undefined} \\
The \livetarg{chap:DWCFAundefined}{DW\-\_CFA\-\_undefined} instruction takes a single unsigned
LEB128\addtoindexx{LEB128!unsigned} operand that represents a register number. The required
body of a function.}
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item \textbf{DW\-\_CFA\-\_remember\-\_state} \\
The \livetarg{chap:DWCFArememberstate}{DW\-\_CFA\-\_remember\-\_state} instruction takes no operands. The
required action is to push the set of rules for every register
onto an implicit stack.
-
+\needlines{4}
\item \textbf{DW\-\_CFA\-\_restore\-\_state} \\
The \livetarg{chap:DWCFArestorestate}{DW\-\_CFA\-\_restore\-\_state} instruction takes no operands. The
required action is to pop the set of rules off the implicit
\subsubsection{Padding Instruction}
\label{chap:paddinginstruction}
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item \textbf{DW\-\_CFA\-\_nop} \\
The \livetarg{chap:DWCFAnop}{DW\-\_CFA\-\_nop} instruction has no operands and no required
actions. It is used as padding to make a CIE or FDE an
(L1), one searches through the FDE headers looking at the
initial\_location and address\_range values to see if L1 is
contained in the FDE. If so, then:}
-
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item \textit{Initialize a register set by reading the
initial\_instructions field of the associated CIE.}
Compilation unit entries may have the following
attributes:
-\begin{enumerate}[1]
+\begin{enumerate}[1. ]
\item Either a \livelink{chap:DWATlowpc}{DW\-\_AT\-\_low\-\_pc} and
\livelink{chap:DWAThighpc}{DW\-\_AT\-\_high\-\_pc} pair of
\addtoindexx{high PC attribute}
relative to the first unit of storage allocated for the
procedure\textquoteright s stack frame. The \livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute
can be used in several ways:}
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item \textit{In procedures that need
\addtoindexx{location list}
location lists to locate local
\livelink{chap:DWATframebase}{DW\-\_AT\-\_frame\-\_base} attribute value should obey the following
constraints:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item It should compute a value that does not change during the
life of the procedure, and
for a subroutine defined explicitly using the instantiation
types. The exceptions are:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item Each formal parameterized type declaration appearing in the
template definition is represented by a debugging information
entry with the
structure and content of its associated abstract instance
tree. There are a few exceptions:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item An entry in the concrete instance tree may be omitted if
it contains only a
\addtoindexx{abstract origin attribute}
representation of a concrete inlined instance of that same
subroutine are as follows:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item The root entry for a concrete out\dash of\dash line instance
of a given inlined subroutine has the same tag as does its
associated (abstract) inlined subroutine entry (that is, tag
\addtoindexx{concrete instance!nested}
concrete instance trees:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item The abstract instance tree for the nested subroutine is
described within the abstract instance tree for the outer
subroutine according to the rules in
For a \livelink{chap:DWATdatamemberlocation}{DW\-\_AT\-\_data\-\_member\-\_location} attribute
\addtoindexx{data member location attribute}
there are two cases:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item If the value is an integer constant, it is the offset
in bytes from the beginning of the containing entity. If
the beginning of the containing entity has a non-zero bit
for a class type defined explicitly using the instantiation
types and values. The exceptions are:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item Each formal parameterized type declaration appearing in the
template definition is represented by a debugging information
entry with the tag
\addtoindexx{type safe enumeration types}
semantics such that
-\begin{enumerate}[1.]
+\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
type entry has a tag whose value has one of two possible
interpretations:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item The formal parameters of a parameter list (that have a
specific type) are represented by a debugging information entry
with the tag \livelink{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter}.
\needlines{4}
The template alias entry has the following child entries:
-\begin{enumerate}[1.]
+\begin{enumerate}[1. ]
\item Each formal parameterized type declaration appearing
in the template alias declaration is represented
by a debugging information entry with the tag
DWARF Git Projects / dwarf-doc.git / commitdiff