\begin{longtable}{ll}
\textbf{Date} & \textbf{Issue Incorporated or Other Change} \\ \hline \\
\endhead
+0/4/2016 & Further Appendix F cleanups \\
+8/31-9/1/2016 & Appendix F editorial additions and corrections \\
+8/8/2016 & Pagination review \\
8/4-7/2016 & 160123.1 (unify location and range lists), 160714.1 (location and range list sections), \\
& 151004.1 (immutable type), usage of \doublequote{should} \\
7/9/2016 & Other editorial \\
various debug information sections. Each contribution is stored
as an offset within its corresponding section and a size.
+\needlines{10}
Each \compunitset{} may contain contributions from the
following sections:
\begin{alltt}
\item \textit{padding} (\HFTuhalf) \\
Reserved to DWARF (must be zero).
+
+\needlines{4}
\item \texttt{section\_count} (\HFTuword) \\
The number of entries in the table of section counts that follows.
For brevity, the contents of this field is referred to as $N$ below.
segmented addressing, this value represents the size of the
offset portion of an address.
-\needlines{6}
+%\needlines{6}
\item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
A
\addtoindexx{section offset!in .debug\_info header}
the primary type contained in this
\addtoindex{type unit} uses this value.}
-\needlines{8}
+%\needlines{8}
\item \texttt{type\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
\addttindexx{type\_offset}
A 4-byte or 8-byte unsigned offset
in the \sixtyfourbitdwarfformat, it is an 8-byte unsigned value
(see Section \refersec{datarep:32bitand64bitdwarfformats}).
+\needlines{10}
\bb
\item \CLASSloclist \\
\livetarg{datarep:classloclist}{}
in the \sixtyfourbitdwarfformat, it is an 8-byte unsigned value
(see Section \refersec{datarep:32bitand64bitdwarfformats}).
+\needlines{8}
\bb
\item \CLASSrnglist \\
\livetarg{datarep:classrnglist}{}
and encoding points as ISO/IEC 10646, as well as additional
information about the characters and their use.}
+\needlines{4}
\textit{Earlier versions of DWARF did not specify the representation
of strings; for compatibility, this version also does
not. However, the UTF\dash 8 representation is strongly recommended.}
Each entry begins with an unsigned 1-byte code that indicates the kind of entry
that follows. The encodings for these constants are given in
-Table \refersec{tab:locationlistentryencodingvalues}.
+Table \ref{tab:locationlistentryencodingvalues}.
\needlines{10}
\begin{centering}
attributes are appended in order according to the alphabetical
spelling of their identifier.
+\needlines{4}
If an implementation defines any vendor-specific attributes,
any such attributes that are essential to the definition of
the type are also included at the end of the above list,
% 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}{August 7, 2016}
+\newcommand{\docdate}{September 4, 2016}
%
\usepackage{ifthen}
\newcommand{\ifthen}[2]{\ifthenelse{#1}{#2}{}}
\usepackage{url} % for color in letters. Links instead?
\usepackage[usenames]{color}%for color in letters. Links instead?
\usepackage{ellipsis} % provides ... as \dots
-\usepackage[utf8]{inputenc}% to type directly diacritic characters
+%\usepackage[utf8]{inputenc}% to type directly diacritic characters
%\usepackage{color}
\usepackage{listings}
\usepackage{alltt}
\listoftables
\ifthenelse{\boolean{isdraft}}
- { %\emptypage
+ { \emptypage
{% Environment to keep the following header change local
\clearpage
\makeevenhead{plain}{}{Change Summary}{}
% Define the levels of sectionality that are numbered.
\setcounter{secnumdepth}{5}
-\uselinenos\include{introduction} %\emptypage
+\uselinenos\include{introduction} \emptypage
\uselinenos\include{generaldescription} %\emptypage
-\uselinenos\include{programscope} %\emptypage
+\uselinenos\include{programscope} \emptypage
\uselinenos\include{dataobject} \emptypage
\uselinenos\include{typeentries} \emptypage
\uselinenos\include{otherdebugginginformation} %\emptypage
-\uselinenos\include{datarepresentation} \emptypage
+\uselinenos\include{datarepresentation} %\emptypage
% The \appendix command toggles us into appendix chapters
\appendix
interpreted by the consumer as a relocatable address
(for example, offsets to thread-local storage).}
-\needlines{12}
+\needlines{8}
\itembfnl{\DWOPconsttypeTARG}
The \DWOPconsttypeNAME{} operation takes three operands. The first operand
is an unsigned LEB128 integer that represents the offset of a debugging
the DWARF expressions, the \DWOPformtlsaddress{} allows the consumer
to perform the computation based on the run-time environment.}
-\needlines{4}
+\needlines{6}
\itembfnl{\DWOPcallframecfaTARG}
The \DWOPcallframecfaNAME{}
operation pushes the value of the
\DWOPpushobjectaddress{} is not meaningful inside of this DWARF operation.
-\textit{
-The values needed to evaluate \DWOPentryvalueNAME{} could be obtained in
+\textit{The values needed to evaluate \DWOPentryvalueNAME{} could be obtained in
several ways. The consumer could suspend execution on entry to the
subprogram, record values needed by \DWOPentryvalueNAME{} expressions within
the subprogram, and then continue; when evaluating \DWOPentryvalueNAME{},
index into a separate section containing location lists).
\eb
-\needlines{4}
+\needlines{8}
\subsection{Single Location Descriptions}
\label{chap:singlelocationdescriptions}
A single location description is either:
description of an object or a piece of an object.
}
+\needlines{4}
The following DWARF operations can be used to
specify a register location.
description (see Section \refersec{chap:singlelocationdescriptions})
that immediately follows.
+\needlines{4}
\item An \definitionx{address index} operand is the index of an address
in the \dotdebugaddr{} section. This index is relative to the
value of the \DWATaddrbase{} attribute of the associated
attribute whose value is the type signature
(see Section \refersec{datarep:typesignaturecomputation}).
-
+\needlines{4}
Not all attributes of the debugging information entry referenced by a
\DWATspecification{} attribute
apply to the referring debugging information entry.
If an entity has no associated machine code,
none of these attributes are specified.
-\needlines{4}
+%\needlines{4}
The \definitionx{base address} of the scope for any of the
debugging information entries listed above is given by either the
\DWATlowpcNAME{}\livetargi{chap:DWATlowpcbaseaddressofscope}{}{base address of scope}
There are several kinds of bounded range entries which specify
the starting and ending addresses in different ways.
-
+\needlines{4}
\item \definition{Base address}.\addtoindexx{base address!of range list}
This kind of entry provides an address to be
used as the base address for the beginning and ending
\end{enumerate}
\eb
-
+\needlines{12}
\section{Entry Address}
\label{chap:entryaddress}
\textit{The entry or first executable instruction generated
\DWATlocation{} attribute, whose value is a
single location description for the run-time constant address.
+\needlines{8}
\section{Alignment}
\label{chap:alignment}
\livetarg{chap:DWATalignmentnondefault}{}
effective at eliminating duplicate data, or even attempts to,
is a quality-of-implementation issue.
+\needlines{6}
\subsection{Leverage Other Standards}
Where another standard exists which describes how to interpret
aspects of a program, DWARF defers to that standard rather than
All names and values not reserved for vendor additions, however,
are reserved for future versions of this document.
+\needlines{4}
Where this specification provides a means for
describing the source language, implementors are expected
to adhere to that specification.
to be compatible with this specification in the absence of
those extensions.
+\needlines{4}
The DWARF format is organized so that a consumer can skip over
data which it does not recognize. This may allow a consumer
to read and process files generated according to a later
version of this standard or which contain vendor extensions,
albeit possibly in a degraded manner.
-\section{Changes From Version 4 to Version 5}
+\section{Changes from Version 4 to Version 5}
\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.
by improving link times.
\item Replace the \dotdebugmacinfo{} macro information representation with
with a \dotdebugmacro{} representation that can potentially be much more compact.
-
\item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
with a single and more functional name index section, \dotdebugnames{}.
+\needlines{4}
\bb
\item Replace the location list and range list sections (\texttt{.debug\_loc}
and \texttt{.debug\_ranges}, respectively) with new sections (\dotdebugloclists{}
\DWTAGtypeunit{}
are used to represent portions of an object file.
+\needlines{4}
\textit{A full compilation unit typically represents the text and
data contributed to an executable by a single relocatable
object file. It may be derived from several source files,
\addtoindexx{ISO-defined language names}
\DWLANGAdaeightythreeTARG{} \dag & ISO Ada:1983 \addtoindexx{Ada:1983 (ISO)} \\
\DWLANGAdaninetyfiveTARG{} \dag & ISO Ada:1995 \addtoindexx{Ada:1995 (ISO)} \\
-\DWLANGCTARG & Non-standardized C, such as K\&R \addtoindexx{C!non-standard}\\
-\DWLANGCeightynineTARG & ISO C:1989 \addtoindexx{C:1989 (ISO)} \\
-\DWLANGCninetynineTARG & ISO C:1999 \addtoindexx{C:1999 (ISO)} \\
-\DWLANGCelevenTARG & ISO C:2011 \addtoindexx{C:2011 (ISO)} \\
+\DWLANGCTARG & Non-standardized C, such as K\&R \addtoindexx{C!non-standard} \\*
+\DWLANGCeightynineTARG & ISO C:1989 \addtoindexx{C:1989 (ISO)} \\*
+\DWLANGCninetynineTARG & ISO C:1999 \addtoindexx{C:1999 (ISO)} \\*
+\DWLANGCelevenTARG & ISO C:2011 \addtoindexx{C:2011 (ISO)} \\*
\DWLANGCplusplusTARG & ISO C++98 \addtoindexx{C++98 (ISO)} \\
\DWLANGCpluspluszerothreeTARG & ISO C++03 \addtoindexx{C++03 (ISO)} \\
\DWLANGCpluspluselevenTARG & ISO C++11 \addtoindexx{C++11 (ISO)} \\
\addtoindex{specialized line number table},
are represented using the UTF-8 representation.
-\item A
-\DWATstroffsetsbase\addtoindexx{string offsets base attribute}
+\needlines{4}
+\item A \DWATstroffsetsbase\addtoindexx{string offsets base attribute}
attribute, whose value is of class \CLASSstroffsetsptr.
This attribute points
to the first string offset of the type unit's contribution to
in Section \refersec{chap:importedorrenameddeclarationentries}.
}
-\needlines{5}
+\needlines{8}
\textit{A \addtoindex{Fortran} use statement for an entity in a module that is
\addtoindexx{Fortran!use statement}
itself imported by a use statement without an explicit mention
indicates whether the subprogram was declared with the \doublequote{noreturn} keyword or property
indicating that the subprogram can be called, but will never return to its caller.
+\needlines{4}
\textit{The \addtoindex{Fortran}
language allows the keywords \texttt{elemental}, \texttt{pure}
and \texttt{recursive} to be included as part of the declaration of
as well as a \DWATconstvalue{} attribute whose value represents
the actual return value of the concrete inlined instance.}
+\needlines{4}
Any debugging information entry that is owned (either
directly or indirectly) by a debugging information entry
with the tag \DWTAGinlinedsubroutine{} is referred to as a
The siblings immediately following a try \nolink{block}
entry are its corresponding catch \nolink{block} entries.
-
+\needlines{8}
\section{Declarations with Reduced Scope}
\label{declarationswithreducedscope}
\hypertarget{chap:DWATstartscopeofdeclaration}{}
that do not require relocation, however, can be written to the
relocatable object (.o) file but ignored by the linker, or they
can be written to a separate DWARF object (.dwo{})
-\addtoindexx{\texttt{.dwo} file extension} file.
+\addtoindexx{\texttt{.dwo} file extension} file
+\bb
+that need not be accessed by the linker.
+\eb
\needlines{4}
The optional set of debugging sections includes the following:
\dotdebugloclistsdwo{} - Contains the location lists referenced by
the debugging information entries in the \dotdebuginfodwo{}
section. This contains the location lists normally found in
-the \dotdebugloclists{} section, with a
-modified format to eliminate the need for relocations.
+the \dotdebugloclists{} section.
+\bbeb
\item
\dotdebugstrdwo{} - Contains the string table for all indirect
strings referenced by the debugging information in the
contains a reference to the corresponding \texttt{.o} or \texttt{.dwo}
file, and the \dotdebugline{} section (which is typically small
compared to the \dotdebuginfo{} sections) is
-linked into the output binary, as is the new \dotdebugaddr{}
-section.
+linked into the output binary, as is the
+\bbeb
+\dotdebugaddr{} section.
\needlines{6}
The debug sections that continue to be linked into the
\item
\dotdebugframe{} - Contains the frame tables.
\item
-\dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
-but no children.
+\dotdebuginfo{} - Contains a skeleton
+\bb
+skeleton compilation unit DIE, which has
+\eb
+no children.
\item
\dotdebugline{} - Contains the line number tables.
(These could be moved to the .dwo file, but in
\end{itemize}
\needlines{6}
-The skeleton \DWTAGcompileunit{} DIE
-may have the following attributes:
+The skeleton
+\bb
+compilation unit
+\eb
+DIE may have the following attributes:
\autocols[0pt]{c}{3}{l}{
\DWATaddrbase{},
\DWATcompdir{},
Relocations are neither necessary nor useful in
\texttt{.dwo} files, because the \texttt{.dwo}
files contain only debugging information that does not need to be
-processed by a linker. Relocations are rendered unnecessary via
-four strategies:
+processed by a linker. Relocations are rendered unnecessary by
+\bb
+these
+\eb
+strategies:
\begin{enumerate}[1. ]
\item Some values needing relocation are kept in the \texttt{.o} file
\texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s},
\texttt{demo1.dwo} and \texttt{demo2.dwo}.
+\bb
+In this section, we will use this example to show how the
+connections between the relocatable object file and the split
+DWARF object file are maintained through the linking process. In
+the next section, we will use this same example to show how two
+or more split DWARF object files are combined into a DWARF
+package file.
+\eb
+
\vspace{2cm}
\begin{figure}[ht]
\textit{File demo1.cc}
\end{figure}
\clearpage
-\subsection{Contents of the Object File}
+\bb
+\subsection{Contents of the Object Files}
+\eb
The object files each contain the following sections of debug
information:
\begin{alltt}
\DWATdwoname: (reference to "demo1.dwo" in .debug_str)
\DWATaddrbase: (reference to .debug_addr section)
\DWATstmtlist: (reference to .debug_line section)
- \DWATlowpc: 0
\end{alltt}
+\bbeb
\end{dwflisting}
-\caption{Split object example: Skeleton DWARF description}
+\caption{Split object example: skeleton DWARF description}
\label{fig:splitdwafexampleskeletondwarfdescription}
\end{figure}
a skeleton compilation unit, and then to a \splitDWARFobjectfile.
+\bb
+\subsection{Contents of the Linked Executable File}
+When \texttt{demo1.o} and \texttt{demo2.o} are linked together (along with
+a main program and other necessary library routines that we will ignore here
+for simplicity), the resulting executable file will contain at least
+the two skeleton compilation units in the \dotdebuginfo{} section, as shown in
+Figure \referfol{fig:splitobjectexampleexecutablefiledwarfexcerpts}.
+\eb
+
+\begin{figure}[ht]
+\bb
+\begin{dwflisting}
+\begin{alltt}
+
+ \DWTAGskeletonunit
+ \DWATcompdir: (reference to directory name in \dotdebugstr)
+ \DWATdwoname: (reference to "demo1.dwo" in \dotdebugstr)
+ \DWATaddrbase: 48 (offset in \dotdebugaddr)
+ \DWATstmtlist: 120 (offset in \dotdebugline)
+ \DWTAGskeletonunit
+ \DWATcompdir: (reference to directory name in \dotdebugstr)
+ \DWATdwoname: (reference to "demo2.dwo" in \dotdebugstr)
+ \DWATaddrbase: 80 (offset in \dotdebugaddr)
+ \DWATstmtlist: 200 (offset in \dotdebugline)
+
+\end{alltt}
+\end{dwflisting}
+\caption{Split object example: executable file DWARF excerpts}
+\label{fig:splitobjectexampleexecutablefiledwarfexcerpts}
+\eb
+\end{figure}
+
+\bb
+Each skeleton compilation unit has a \DWATstmtlist{} attribute,
+which provides the relocated offset to that compilation unit's
+contribution in the executable's \dotdebugline{} section. In this
+example, the line number information for \texttt{demo1.dwo} begins at
+offset 120, and for \texttt{demo2.dwo}, it begins at offset 200.
+
+\needlines{4}
+Each skeleton compilation unit also has a \DWATaddrbase{}
+attribute, which provides the relocated offset to that
+compilation unit's contribution in the executable's \dotdebugaddr{}
+section. Unlike the \DWATstmtlist{} attribute, the offset refers
+to the first address table slot, not to the section header. In
+this example, we see that the first address (slot 0) from \texttt{demo1.o}
+begins at offset 48. Because the \dotdebugaddr{} section contains an
+8-byte header, the object file's contribution to the section
+actually begins at offset 40 (for a 64-bit DWARF object, the
+header would be 16 bytes long, and the value for the
+\DWATaddrbase{} attribute would then be 56). All attributes in
+\texttt{demo1.dwo} that use \DWFORMaddrx{} would then refer to address
+table slots relative to that offset. Likewise, the \dotdebugaddr{}
+contribution from \texttt{demo2.dwo} begins at offset 72, and its first
+address slot is at offset 80. Because these contributions have
+been processed by the linker, they contain relocated values for
+the addresses in the program that are referred to by the debug
+information.
+
+The linked executable will also contain \dotdebugabbrev,
+\dotdebugstr{}, \dotdebugnames{} and \dotdebugaranges{} sections, each the
+result of combining and relocating the contributions from the
+relocatable object files.
+\eb
+
+\needlines{10}
\subsection{Contents of the Split DWARF Object Files}
The \splitDWARFobjectfile{s} each contain the following sections:
\begin{alltt}
That slot contains the relocated address of the beginning of the
function.
+\needlines{6}
Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
section, and looks like a normal type unit in a non-split object,
except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
The offsets in these slots have no associated relocations,
because they are not part of a relocatable object file.
-
-\needlines{4}
When combined into a DWARF package file, however, each
slot must be adjusted to refer to the appropriate offset
within the merged string table (\dotdebugstrdwo{}).
an example of a DWARF package file.
\needlines{4}
+\bb
+The \dotdebugrnglistsdwo{} section contains range lists referenced by any
+\DWATranges{} attributes in the split DWARF object. In our example,
+\texttt{demo1.o} would have just a single range list for the compilation unit,
+with range list entries for the function \texttt{Box::contains} and for
+out-of-line copies of the inline functions \texttt{Point::x} and \texttt{Point::y}.
+\eb
+
The \dotdebugloclistsdwo{} section contains the location lists referenced
by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
section has a similar format to the \bbeb\dotdebugloclists{} section in a
type unit for class \texttt{Box} from \texttt{demo1.dwo} \newline
type unit for class \texttt{Point} from \texttt{demo1.dwo} \newline
type unit for class \texttt{Line} from \texttt{demo2.dwo} \\
+\hline
+\bb
+ \dotdebugrnglistsdwo{}
+& \dotdebugrnglistsdwo{} from \texttt{demo1.dwo} \newline
+ \dotdebugrnglistsdwo{} from \texttt{demo2.dwo}
+\eb \\
\hline
\dotdebugloclistsdwo{}
& \dotdebugloclistsdwo{} from \texttt{demo1.dwo} \newline
\end{figure}
\needlines{4}
-The \dotdebugabbrevdwo{}, \dotdebugloclistsdwo{} and \dotdebuglinedwo{}
+The \dotdebugabbrevdwo{},
+\bb
+\dotdebugrnglistsdwo{},
+\eb
+\dotdebugloclistsdwo{} and \dotdebuglinedwo{}
sections are copied over from the two \texttt{.dwo} files as
individual contributions to the corresponding sections in the
\texttt{.dwp} file.
\begin{figure}[ht]
\begin{center}
-\begin{tabular}{lrrrrrr}
+\begin{tabular}{lrrrrrrr}
\\
\multicolumn{7}{c}{Section header} \\
\hline \\
- \multicolumn{2}{l}{Version:}& 5 &&&&\\
- \multicolumn{2}{l}{Number of columns:}& 5 &&&&\\
- \multicolumn{2}{l}{Number of used entries:}& 2 &&&&\\
- \multicolumn{2}{l}{Number of slots:}& 16 &&&&\\
+ \multicolumn{2}{l}{Version:}& 5 &&&&&\\
+ \multicolumn{2}{l}{Number of columns:}& 6\bbeb &&&&&\\
+ \multicolumn{2}{l}{Number of used entries:}& 2 &&&&&\\
+ \multicolumn{2}{l}{Number of slots:}& 16 &&&&&\\
\\
\multicolumn{7}{c}{Offset table} \\
\hline
- slot& signature& info& abbrev& loc& line& str\_off \\
- 14& \texttt{0xb5f0ecf455e7e97e}& 325& 452& 84& 52& 72 \\
- 15& \texttt{0x044e413b8a2d1b8f}& 0& 0& 0& 0& 0 \\
+\bbeb slot& signature& info& abbrev& loc& line& str\_off& rng \\
+\bbeb 14& \texttt{0xb5f0ecf455e7e97e} & 325& 452& 84& 52& 72& 350 \\
+\bbeb 15& \texttt{0x044e413b8a2d1b8f} & 0& 0& 0& 0& 0& 0 \\
\\
\multicolumn{7}{c}{Size table} \\
\hline
- slot& & info& abbrev& loc& line& str\_off \\
- 14& & 673& 593& 93& 52& 120 \\
- 15& & 325& 452& 84& 52& 72 \\
+\bbeb slot& & info& abbrev& loc& line& str\_off& rng \\
+\bbeb 14& & 673& 593& 93& 52& 120& 34 \\
+\bbeb 15& & 325& 452& 84& 52& 72& 15 \\
\\ \hline
\end{tabular}
\end{center}
DWARF Git Projects / dwarf-doc.git / commitdiff