\begin{longtable}{ll}
\textbf{Date} & \textbf{Issue Incorporated or Other Change} \\ \hline \\
\endhead
-6/5-7/2015 & Add color to defining occurrence(s) of DWARF names. Choices include: \\
- & \textcolor{red}{red}, \textcolor{green}{green}, \textcolor{blue}{blue},
- \textcolor{yellow}{yellow}, \textcolor{cyan}{cyan}, \textcolor{magenta}{magenta} \\
+6/14/2015 & More editorial work VII \\
+6/8-13/2015 & More editorial work VI (release to committee) \\
+6/5-7/2015 & Add \definition{color} to defining occurrence(s) of DWARF names. \\
5/19-6/4/2015 & More editorial work V \\
5/14-16/2015 & More editorial work IV (release to committee) \\
5/12-13/2015 & More editorial work III (Appendix B)\\
\chapter[Compression (Informative)]{DWARF Compression and Duplicate Elimination (Informative)}
-\label{dwarfcompressionandduplicateeliminationinformative}
+\label{app:dwarfcompressionandduplicateeliminationinformative}
% It seemed difficult to get close to the same layout and
% captioning as DWARF4 here with figures as they moved (floated)
These attributes refer to
debugging information in other debugging information sections within
the object file, and must be relocated during the linking process.
-Exception: attributes whose values are relative to a base offset given
-by \DWATrangesbase{} do not need relocation.
+
+However, if a \DWATrangesbase{} attribute is present, the offset in
+a \DWATranges{} attribute (which uses form \DWFORMsecoffset) is
+relative to the given base offset {no relocation is involved}.
\item Debugging information entries may have attributes with the form
\DWFORMrefone, \DWFORMreftwo, \DWFORMreffour, \DWFORMrefeight, or
A DWARF producer may partition the debugging
information such that the majority of the debugging
information can remain in individual object files without
-being processed by the linker. The first partition contains
+being processed by the linker.
+
+\subsubsection{First Partition (with Skeleton Unit)}
+The first partition contains
debugging information that must still be processed by the linker,
and includes the following:
\begin{itemize}
unit can be used by a DWARF consumer to find the object file
or DWARF object file that contains the second partition.
+\subsubsection{Second Partition (Unlinked or In \texttt{.dwo} File)}
The second partition contains the debugging information that
does not need to be processed by the linker. These sections
may be left in the object files and ignored by the linker
\begin{itemize}
\item
The full compilation unit, in the \dotdebuginfodwo{} section.
-Attributes in debugging information entries may refer to
-machine addresses indirectly using the \DWFORMaddrx{} form,
-and location expressions may do so using the \DWOPaddrx{} and
-\DWOPconstx{} forms. Attributes may refer to range table
-entries with an offset relative to a base offset in the
-range table for the compilation unit.
-
+\begin{itemize}
+\item
+The full compilation unit entry includes a \DWATdwoid{}
+attribute whose value is the same as that of the \DWATdwoid{}
+attribute of the associated skeleton unit.
+\needlines{4}
+\item
+Attributes contained in the full compilation unit
+may refer to machine addresses indirectly using the \DWFORMaddrx{}
+form, which accesses the table of addresses specified by the
+\DWATaddrbase{} attribute in the associated skeleton unit.
+Location expressions may similarly do so using the \DWOPaddrx{} and
+\DWOPconstx{} operations.
+\item
+\DWATranges{} attributes contained in the full compilation unit
+may refer to range table entries with a \DWFORMsecoffset{} offset
+relative to the base offset specified by the \DWATrangesbase{}
+attribute in the associated skeleton unit.
+\end{itemize}
\item Separate type units, in the \dotdebuginfodwo{} section.
\item
Split DWARF object files do not get linked with any other files,
therefore references between sections must not make use of
-normal object file relocation information.
+normal object file relocation information. As a result, symbolic
+references within or between sections are not possible.
\subsection{Executable Objects}
\label{chap:executableobjects}
The relocated addresses in the debugging information for an
executable object are virtual addresses.
+\needlines{6}
\subsection{Shared Object Files}
\label{datarep:sharedobject Files}
The relocated
\addtoindexx{DWARF package files}
same object file format (including \byteorder) as the
corresponding application binary. It consists only of a file
-header, section table, a number of DWARF debug information
+header, a section table, a number of DWARF debug information
sections, and two index sections.
\needlines{5}
The string table section in \dotdebugstrdwo{} contains all the
strings referenced from DWARF attributes using the form
\DWFORMstrx. Any attribute in a compilation unit or a type
-unit using this form will refer to an entry in that unit's
+unit using this form refers to an entry in that unit's
contribution to the \dotdebugstroffsetsdwo{} section, which in turn
-will provide the offset of a string in the \dotdebugstrdwo{}
+provides the offset of a string in the \dotdebugstrdwo{}
section.
The DWARF package file also contains two index sections that
\dotdebugstroffsetsdwo
\end{alltt}
+\textit{Merging of type units with the same type signature
+across \texttt{.dwo} files when creating a \texttt{.dwp} file
+can be achieved using COMDAT-based techniques similar to those
+described in Appendix
+\refersec{app:dwarfcompressionandduplicateeliminationinformative}.
+In fact, this is necessary in order to combine all \dotdebuginfodwo{}
+section contributions into a single \dotdebuginfodwo{} section in a
+\texttt{.dwp} file.}
+
\subsubsection{Format of the CU and TU Index Sections}
Both index sections have the same format, and serve to map a
64-bit signature to a set of contributions to the debug sections.
The version number is \versiondotdebugcuindex.
\item \textit{padding} (\HFTuhalf) \\
-Reserved to DWARF.
+Reserved to DWARF (must be zero).
\item \texttt{column\_count} (\HFTuword) \\
The number of columns in the table of section counts that follows.
abbreviation code is followed by another unsigned LEB128\addtoindexx{LEB128!unsigned}
number that encodes the entry\textquoteright s tag. The encodings for the
tag names are given in
-Table \refersec{tab:tagencodings}.
+Table \referfol{tab:tagencodings}.
\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|c}
- \hline
\caption{Tag encodings} \label{tab:tagencodings} \\
\hline \bfseries Tag name&\bfseries Value\\ \hline
\endfirsthead
Table \refersec{tab:attributeencodings}
determines the class of the form.
+\needlines{4}
In the form descriptions that follow, some forms are said
to depend in part on the value of an attribute of the
\definition{\associatedcompilationunit}:
\item \livelink{chap:classblock}{block} \\
\livetarg{datarep:classblock}{}
Blocks come in four forms:
-
-\begin{myindentpara}{1cm}
+\begin{itemize}
+\item
A 1-byte length followed by 0 to 255 contiguous information
bytes (\DWFORMblockoneTARG).
-\end{myindentpara}
-\begin{myindentpara}{1cm}
+\item
A 2-byte length followed by 0 to 65,535 contiguous information
bytes (\DWFORMblocktwoTARG).
-\end{myindentpara}
-\begin{myindentpara}{1cm}
+\item
A 4-byte length followed by 0 to 4,294,967,295 contiguous
information bytes (\DWFORMblockfourTARG).
-\end{myindentpara}
-\begin{myindentpara}{1cm}
+\item
An unsigned LEB128\addtoindexx{LEB128!unsigned}
length followed by the number of bytes
specified by the length (\DWFORMblockTARG).
-\end{myindentpara}
+\end{itemize}
In all forms, the length is the number of information bytes
that follow. The information bytes may contain any mixture
or location description
(see Section \refersec{chap:locationdescriptions}).
+\needlines{4}
\item \livelinki{chap:classflag}{flag}{flag class} \\
\livetarg{datarep:classflag}{}
A flag \addtoindexx{flag class}
information for the referencing entity.
It is relocatable in
a relocatable object file, and relocated in an executable or
-shared object file. In the \thirtytwobitdwarfformat, this offset
+shared object file.
+However, if a \DWATrangesbase{} attribute applies, the offset
+is relative to the base offset given by \DWATrangesbase.
+In the \thirtytwobitdwarfformat, this offset
is a 4-byte unsigned value; in the 64-bit DWARF
format, it is an 8-byte unsigned value (see Section
\refersec{datarep:32bitand64bitdwarfformats}).
it is an 8-byte unsigned offset
(see Section \refersec{datarep:32bitand64bitdwarfformats}).
-\needlines{4}
+\needlines{6}
\item as an indirect offset into the string table using an
index into a table of offsets contained in the
\dotdebugstroffsets{} section of the object file (\DWFORMstrxTARG).
following the header. The entries are referenced by a byte
offset relative to this base address.
-
+\needlines{12}
\section{Location List Table}
\label{datarep:locationlisttable}
Each set of entries in the location list table contained in the
\section{Type Signature Computation}
\label{datarep:typesignaturecomputation}
-A type signature is computed only by the DWARF producer;
-\addtoindexx{type signature!computation}
-it is used by a DWARF consumer to resolve type references to
-the type definitions that are contained in
-\addtoindexx{type unit}
-type units.
+A \addtoindex{type signature} is used by a DWARF consumer
+to resolve type references to the type definitions that
+are contained in \addtoindex{type unit}s (see Section
+\refersec{chap:typeunitentries}).
+
+\textit{A type signature is computed only by a DWARF producer;
+\addtoindexx{type signature!computation} a consumer need
+compare two type signatures to check for equality.}
\needlines{4}
The type signature for a type T0 is formed from the
as the marker, process the type T recursively by performing
Steps 2 through 7, and use the result as the attribute value.
+\needlines{4}
Other attribute values use the letter 'A' as the marker, and
the value consists of the form code (encoded as an unsigned
LEB128 value) followed by the encoding of the value according
% 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}{June 7, 2015}
+\newcommand{\docdate}{June 14, 2015}
%
\usepackage{ifthen}
\newboolean{isdraft}
\newpage
\tableofcontents
-\newpage
-~ % Make non-empty
-\cleardoublepage
+\clearpage
\listoffigures
-\cleardoublepage
+\clearpage
\listoftables
\ifthenelse{\boolean{isdraft}}
\include{dataobject} %\emptypage
\include{typeentries} %\emptypage
\include{otherdebugginginformation} \emptypage
-\include{datarepresentation} %\emptypage
+\include{datarepresentation} \emptypage
% The \appendix toggles us into appendix chapters
\appendix
more compact and/or more expressive.
\clearpage
-The \dwf\ Committee is open to compiler and debugger
+{\bfseries The \dwf{} Committee}
+
+The \dwf{} Committee is open to compiler and debugger
developers who have experience with source language debugging
and debugging formats, and have an interest in promoting or
extending the DWARF debugging format.
\url{http://www.dwarfstd.org}
\end{myindentpara}
+\clearpage
+{\bfseries How to Use This Document}
+
This document is intended to be usable in online as well as
-traditional paper forms.
+traditional paper forms. Both online and paper forms include
+page numbers, a Table of Contents, a List of Figures,
+a List of Tables and an Index.
+
+\textit{Online Form}
In the online form, blue text is used to indicate hyperlinks.
-% which facilitate moving around
-%in the document in a manner like that typically found in web
-%browsers.
Most hyperlinks link to the definition of a term or
construct, or to a cited Section or Figure.
However, attributes
in particular are often used in more than one way or context so
that there is no single definition; for attributes, hyperlinks
-link to the introductory list of all attributes which in turn
-contains hyperlinks for the multiple usages.
-The Table of
-Contents also provides hyperlinks to the respective sections.
+link to the introductory table of all attributes which in turn
+contains hyperlinks for the multiple usages.
+
+The occurrence of
+a DWARF name in its definition (or one of its definitions in the
+case of some attributes) is shown in \definition{color}. Other
+occurrences of the same name in the same or possibly following
+paragraphs are generally in normal text color.)
+
+The Table of Contents, List of Figures, List of Tables and Index provide hyperlinks to the
+respective items and places.
+
+\textit{Paper Form}
In the traditional paper form, the appearance of the hyperlinks
-on a page of paper does not distract the eye because the blue
-hyperlinks are typically imaged by black and white printers in
+and definitions on a page of paper does not distract the eye
+because the blue hyperlinks and the color used for definitions
+are typically imaged by black and white printers in
a manner nearly indistinguishable from other text.
(Hyperlinks are not underlined for this same reason.)
-Both online and paper forms include
-page numbers, a Table of Contents, a List of Figures and an Index.
\end{abstract}
entries of any node are exactly those debugging information
entries owned by that node.
+\needlines{4}
\textit{%
While the ownership relation
of the debugging information entries is represented as a
(see Section \refersec{chap:statemachineregisters}).
}
+\needlines{4}
\section{DWARF Expressions}
\label{chap:dwarfexpressions}
DWARF expressions describe how to compute a value or name a
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.
-\textit{While the size of the constant could be inferred from the base 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
operation can be parsed easily without reference to the \dotdebuginfo{}
section.}
object that is present in the source but not in the object code
(perhaps due to optimization).
-\needlines{5}
+\needlines{6}
\subsubsection{Composite Location Descriptions}
A composite location description describes an object or
value which may be contained in part of a register or stored
DWARF Version 5 is compatible with DWARF Version 4 except as follows:
\begin{itemize}
-\item The line number table header is substantially revised.
+\item The compilation unit header (in the \dotdebuginfo{} section) has
+a new \HFNunittype{} field.
+\needlines{4}
\item New operand forms for attribute values are defined
(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME,
-\DWFORMrefsupNAME, \DWFORMstrpsupNAME, \DWFORMstrxNAME).
+\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)
+is substantially revised.
\needlines{4}
\item A location list entry (see Section \refersec{chap:locationlists})
with the address range \mbox{(0, \textit{maximum-address})} is defined
\needlines{8}
\item A \DWATstroffsetsbaseDEFN\addtoindexx{string offset base attribute}
\hypertarget{chap:DWATstroffsetbaseforindirectstringtable}{}
-attribute, whose value is a reference.
+attribute, whose value is of class \CLASSstroffsetsptr.
This attribute points to the first string
offset of the compilation unit's contribution to the
\dotdebugstroffsets{} (or \dotdebugstroffsetsdwo{}) section.
interpreted as indices relative to this base.
\needlines{6}
-\item A \DWATaddrbaseNAME\addtoindexx{address table base attribute}
+\item A \DWATaddrbaseTARG\addtoindexx{address table base attribute}
\hypertarget{chap:DWATaddrbaseforaddresstable}{}
-attribute, whose value is a reference.
+attribute, whose value is of class \CLASSaddrptr.
This attribute points to the beginning of the compilation
unit's contribution to the \dotdebugaddr{} section.
Indirect references (using \DWFORMaddrx, \DWOPaddrx,
\needlines{5}
\item A \DWATrangesbaseDEFN\addtoindexx{ranges table base attribute}
\hypertarget{chap:DWATrangesbaseforrangelists}{}
-attribute, whose value is a reference.
+attribute, whose value is of class \CLASSrangelistptr.
This attribute points to the beginning of the compilation
unit's contribution to the \dotdebugranges{} section.
References to range lists (using \DWFORMsecoffset)
have a \DWATimportDEFN{} attribute that refers to the entry for the
entity being imported. (\addtoindex{C++}
provides no means to \doublequote{rename}
-an imported entity, other than a namespace).
-}
+an imported entity, other than a namespace).}
+
\textit{A \addtoindex{Fortran} use statement
\addtoindexx{Fortran!use statement}
in Section \refersec{chap:importedorrenameddeclarationentries}.
}
+\needlines{5}
\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
A catch \nolink{block}
designates the type of the exception that it can handle.}
-A \livetargi{chap:tryblock}{try block}{try block} is represented
+A \livetarg{chap:tryblock}{try block} is represented
by a debugging information entry
\addtoindexx{try block entry}
with the tag \DWTAGtryblockTARG.
-A \livetargi{chap:catchblock}{catch block} is represented by
+A \livetarg{chap:catchblock}{catch block} is represented by
a debugging information entry
\addtoindexx{catch block entry}
with the tag \DWTAGcatchblockTARG.
information for the compilation unit that is normally found
in the \dotdebuginfo{} section.
\item
-\dotdebugabbrevdwo{} - Contains the abbreviations tables used by
+\dotdebugabbrevdwo{} - Contains the abbreviations table(s) used by
the \dotdebuginfodwo{} sections.
\item
\dotdebuglocdwo{} - Contains the location lists referenced by
\end{itemize}
-In a .dwo file there is no benefit to having a separate string
+In a \texttt{.dwo} file there is no benefit to having a separate string
section for directories and file names because the primary
string table will never be stripped. Accordingly, no
-\texttt{.debug\_line\_str.dwo} is defined. Content descriptions corresponding
-to \DWFORMlinestrp{} in an executable file (for example, in the
-skeleton compilation unit) instead use \DWFORMstrx. This allows
+\texttt{.debug\_line\_str.dwo} section is defined. Content descriptions
+corresponding to \DWFORMlinestrp{} in an executable file (for example,
+in the skeleton compilation unit) instead use \DWFORMstrx. This allows
directory and file name strings to be merged with general
strings and across compilations in package files (which are not
subject to potential stripping).
-
+In a \texttt{.dwo} file. referring to a string using \DWFORMstrp{}
+is valid, but such use may complicate incorporation of that file into a
+\texttt{.dwp} file due to changed string offsets as a result of string merging.
In order for the consumer to locate and process the debug
information, the compiler must produce a small amount of debug
\item Template parameters are described and referenced as
specified in Section \refersec{chap:templateparameters}.
-\needlines{4}
+%\needlines{4}
\item If the compiler has generated a special compilation unit to
hold the
\addtoindexx{template instantiation!and special compilation unit}
information entry representing the special compilation unit
should be empty or omitted.
-\needlines{4}
+%\needlines{4}
\item If the class type entry representing the template
instantiation or any of its child entries contains declaration
coordinate attributes, those attributes should refer to
\DWDSCrangeTARG{} \\
\end{simplenametable}
+\needlines{4}
If a variant entry has neither a \DWATdiscrvalue{}
attribute nor a \DWATdiscrlist{} attribute, or if it has
a \DWATdiscrlist{} attribute with 0 size, the variant is a
type of an array element if the parent has an array type;
otherwise it is the type of the parent entry.
-\needlines{4}
+%\needlines{4}
The condition entry owns \DWTAGconstant{} and/or
\DWTAGsubrangetype{} entries that describe the constant
values associated with the condition. If any child entry
whose value (see Section \refersec{chap:byteandbitsizes}) is
the amount of storage needed to hold a value of the set type.
-
+\needlines{5}
\section{Subrange Type Entries}
\label{chap:subrangetypeentries}
DWARF Git Projects / dwarf-doc.git / commitdiff