&\livelink{chap:DECL}{DECL} \\
&\DWATabstractorigin{} \\
&\DWATaccessibility{} \\
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\hline
\DWTAGatomictype
&\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\hline
\DWTAGbasetype
&\livelink{chap:DECL}{DECL} \\
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbinaryscale{} \\
\hline
\DWTAGcatchblock
&\livelink{chap:DECL}{DECL} \\*
-&\DWATabstractorigin{} \\
-&\DWATentrypc{} \\
+&\DWATabstractorigin{} \\*
+&\DWATentrypc{} \\*
&\DWAThighpc{} \\
&\DWATlowpc{} \\
-&\DWATranges{} \\
-&\DWATsegment{} \\
-&\DWATsibling{} \\
+&\DWATranges{} \\*
+&\DWATsegment{} \\*
+&\DWATsibling{} \\*
\hline
\DWTAGclasstype
&\livelink{chap:DECL}{DECL} \\*
&\DWATabstractorigin{} \\*
&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\DWTAGcoarraytype
&\livelink{chap:DECL}{DECL} \\*
&\DWATname{} \\*
-&\DWATdescription{} \\*
+&\DWATdescription{} \\
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\hline
\DWTAGconsttype
&\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\DWTAGdynamictype
&\livelink{chap:DECL}{DECL} \\*
&\DWATabstractorigin \\*
-&\DWATallocated \\*
+&\DWATalignment{} \\*
+&\DWATallocated \\
&\DWATassociated \\
&\DWATdatalocation \\
&\DWATdescription \\
\hline
\DWTAGenumerationtype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\hline
\DWTAGenumerator
-&\livelink{chap:DECL}{DECL} \\
-&\DWATconstvalue{} \\
-&\DWATdescription{} \\
-&\DWATname{} \\
-&\DWATsibling{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATconstvalue{} \\*
+&\DWATdescription{} \\*
+&\DWATname{} \\*
+&\DWATsibling{} \\*
\hline
\DWTAGfiletype
&\livelink{chap:DECL}{DECL} \\*
&\DWATabstractorigin{} \\*
-&\DWATallocated{} \\*
+&\DWATalignment{} \\*
+&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
&\DWATbytesize{} \\
&\DWATlocation{} \\
&\DWATname{} \\
&\DWATsegment{} \\
-&\DWATsibling{} \\
-&\DWATtype{} \\
-&\DWATvariableparameter{} \\
+&\DWATsibling{} \\*
+&\DWATtype{} \\*
+&\DWATvariableparameter{} \\*
\hline
\DWTAGfriend
\hline
\DWTAGinterfacetype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\*
&\DWATdescription{} \\
&\DWATname{} \\*
&\DWATsibling{} \\*
\hline
\DWTAGpackedtype
&\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\DWTAGpointertype
&\livelink{chap:DECL}{DECL} \\*
&\DWATaddressclass{} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\hline
\DWTAGptrtomembertype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaddressclass{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaddressclass{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATcontainingtype{} \\
\DWTAGreferencetype
&\livelink{chap:DECL}{DECL} \\*
&\DWATaddressclass{} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\hline
\DWTAGrestricttype
&\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\DWTAGrvaluereferencetype
&\livelink{chap:DECL}{DECL} \\*
&\DWATaddressclass{} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\hline
\DWTAGsettype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\DWTAGsharedtype
&\livelink{chap:DECL}{DECL} \\*
&\DWATcount{} \\*
+&\DWATalignment{} \\*
&\DWATsibling{} \\*
&\DWATtype{} \\*
\DWTAGstringtype
&\livelink{chap:DECL}{DECL} \\*
&\DWATabstractorigin{} \\*
-&\DWATaccessibility{} \\*
+&\DWATalignment{} \\*
+&\DWATaccessibility{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\hline
\DWTAGstructuretype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\DWTAGsubprogram
&\livelink{chap:DECL}{DECL} \\*
&\DWATabstractorigin{} \\*
-&\DWATaccessibility{} \\
+&\DWATaccessibility{} \\*
&\DWATaddressclass{} \\
+&\DWATalignment{} \\
&\DWATartificial{} \\
&\DWATcallingconvention{} \\
&\DWATdeclaration{} \\
\hline
\DWTAGsubrangetype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\hline
\DWTAGsubroutinetype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
&\DWATaddressclass{} \\
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATdatalocation{} \\
\hline
\DWTAGthrowntype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATallocated{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATalignment{} \\*
+&\DWATallocated{} \\*
&\DWATassociated{} \\
&\DWATdatalocation{} \\
&\DWATsibling{} \\
&\livelink{chap:DECL}{DECL} \\*
&\DWATabstractorigin{} \\*
&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATdatalocation{} \\
\hline
\DWTAGuniontype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATallocated{} \\
&\DWATassociated{} \\
&\DWATbitsize{} \\
\hline
\DWTAGvariable
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATaccessibility{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATaccessibility{} \\*
+&\DWATalignment{} \\
&\DWATartificial{} \\
&\DWATconstexpr{} \\
&\DWATconstvalue{} \\
\begin{longtable}{ll}
\textbf{Date} & \textbf{Issue Incorporated or Other Change} \\ \hline \\
\endhead
+9/25/2014 & 140724.1 (line number table header), pre-release cleanups \\
+9/23/2014 & 140528.1 (alignment attribute), 120604.1 (supplementary macro sections) \\
8/22/2014 & Miscellaneous editorial corrections, indexing improvements \\
7/22/2014 & Add items in Section 1.4, Changes from Version 4 to Version 5 \\
7/21/2014 & Enable section numbers on pdf bookmarks \\
10/26/2013 & 130313.1 (indirect string table), 130313.2 (indirect address table), \\
& 130313.3 (ranges without relocations), 130313.4 (split objects) \\
10/25/2013 & 130530.1 (MD5 wording), 131017.1 (\DWATentrypcNAME{} descriptions), \\
- & 130701.1 (MD5 digest for file names in line table), 100831.1 (implicit pointers) \\
+ & 130701.1 (MD5 digest for filenames in line number table), 100831.1 (implicit pointers) \\
10/24/2013 & 130815.1 (template parameter refactoring) \\
10/23/2013 & 130722.1 (additional \DWATartificialNAME{} uses in Appendix A), \\
& 120719.1 (constant \DWATentrypcNAME{} value), \\
\item
The line number tables, range tables, frame tables, and
accelerated access tables, in the usual sections:
-\dotdebugline, \dotdebugranges, \dotdebugframe,
+\dotdebugline, \dotdebuglinestr, \dotdebugranges, \dotdebugframe,
\dotdebugpubnames, \dotdebugpubtypes{} and \dotdebugaranges,
respectively.
+\needlines{4}
\item
An address table, in the \dotdebugaddr{} section. This table
contains all addresses and constants that require
\item Location lists, in the \dotdebuglocdwo{} section.
\item
-A skeleton line table (for the type units), in the
+A skeleton line number table (for the type units), in the
\dotdebuglinedwo{} section (see
Section \refersec{chap:skeletoncompilationunitentries}).
the array is indexed starting from 1 (row 0 of the table of
offsets also serves as the key for the table of sizes).
+\subsection{DWARF Supplementary Object Files}
+\label{data:dwarfsupplemetaryobjectfiles}
+In order to minimize the size of debugging information, it is possible
+to move duplicate debug information entries, strings and macro entries from
+several executables or shared objects into a separate
+\addtoindexi{\textit{supplementary object file}}{supplementary object file} by some
+post-linking utility; the moved entries and strings can be then referenced
+from the debugging information of each of those executables or shared objects.
+
+A DWARF supplementary object file is itself an object file, using the same object
+file format, byte order, and size as the corresponding application executables
+or shared libraries. It consists only of a file header, section table, and
+a number of DWARF debug information sections. Both the supplementary object file
+and all the executables or shared objects that reference entries or strings in that
+file must contain a \dotdebugsup{} section that establishes the relationship.
+
+The \dotdebugsup section contains:
+\begin{enumerate}[1. ]
+\item \texttt{version} (uhalf) \\
+A 2-byte unsigned integer representing the version of the DWARF
+information for the compilation unit (see Appendix G). The
+value in this field is \versiondotdebugsup.
+
+\item \texttt{is\_supplementary} (ubyte) \\
+A 1-byte unsigned integer, which contains the value 1 if it is
+in the \addtoindex{supplementary object file} that other executables or
+shared objects refer to, or 0 if it is an executable or shared object
+referring to a supplemental object file file.
+
+\needlines{4}
+\item \texttt{sup\_filename} (null terminated filename string) \\
+If \texttt{is\_supplementary} is 0, this contains either an absolute
+filename for the supplementary object file, or a filename relative to
+the object file containing the \dotdebugsup{} section.
+If \texttt{is\_supplementary} is 1, then \texttt{sup\_filename}
+is not needed and must be an empty string (a single nul byte).
+
+\needlines{4}
+\item \texttt{sup\_checksum\_len} (unsigned LEB128) \\
+Length of the following \texttt{sup\_checksum} field;
+his value can be 0 if no checksum is provided.
+
+
+\item \texttt{sup\_checksum} (array of ubyte) \\
+Some checksum or cryptographic hash function of the \dotdebuginfo{},
+\dotdebugstr{} and \dotdebugmacro{} sections of the
+\addtoindex{supplementary object file}, or some unique identifier
+which the implementation can choose to verify that the supplementary
+section object file matches what the debug information in the executables
+or shared objects expects.
+\end{enumerate}
+
+Debug information entries that refer to an executable's or shared
+object's addresses must \emph{not} be moved to supplementary files (the
+addesses will likely not be the same). Similarly,
+entries referenced from within locationexpressions or using loclistptr
+form attributes must not be moved.
+
+Executable or shared object compilation units can use
+\DWTAGimportedunit{} with \DWFORMrefsup{} form \DWATimport{} attribute
+to import entries from the supplementary object file, other \DWFORMrefsup{}
+attributes to refer to them and \DWFORMstrpsup{} form attributes to
+refer to strings that are used by debug information of multiple
+executables or shared objects. Within the \addtoindex{supplementary object file}'s
+debugging sections, form \DWFORMrefsup{} or \DWFORMstrpsup{} should
+not be used, and all reference forms referring to some other sections
+refer to the local sections in the supplementary object file.
+
+In macro information, \DWMACROdefineindirectsup{} or
+\DWMACROundefindirectsup{} opcodes can refer to strings in the
+\dotdebugstr section of the supplementary file, or \DWMACROtransparentincludesup{}
+can refer to \dotdebugmacro section entries. Within the
+\dotdebugmacro{} section of a \addtoindex{supplementary object file},
+\DWMACROdefineindirect{} and \DWMACROundefindirect{}
+opcodes refer to the local \dotdebugstr{} section, not the one in
+the executable or shared object."
+
+
\needlines{6}
\section{32-Bit and 64-Bit DWARF Formats}
\label{datarep:32bitand64bitdwarfformats}
the value is a 32\dash bit unsigned integer; for the 64\dash bit DWARF
format, the value is a 64\dash bit unsigned integer.
\begin{center}
-\begin{tabular}{ll}
-Form & Role \\ \hline
-\DWFORMrefaddr& offset in \dotdebuginfo{} \\
-\DWFORMsecoffset& offset in a section other than \\
- &\dotdebuginfo{} or \dotdebugstr{} \\
-\DWFORMstrp&offset in \dotdebugstr{} \\
-\DWOPcallref&offset in \dotdebuginfo{} \\
+\begin{tabular}{lp{6cm}}
+Form & Role \\ \hline
+\DWFORMlinestrp & offset in \dotdebuglinestr \\
+\DWFORMrefaddr & offset in \dotdebuginfo{} \\
+\DWFORMrefsup & offset in \dotdebuginfo{} section of a \mbox{supplementary} object file \\
+ \addtoindexx{supplementary object file}
+\DWFORMsecoffset & offset in a section other than \\
+ & \dotdebuginfo{} or \dotdebugstr{} \\
+\DWFORMstrp & offset in \dotdebugstr{} \\
+\DWFORMstrpsup & offset in \dotdebugstr{} section of a \mbox{supplementary} object file \\
+\DWOPcallref & offset in \dotdebuginfo{} \\
+\end{tabular}
+\end{center}
+
+\needlines{5}
+\item Within the body of the \dotdebugline{} section, certain forms of content
+description depend on the choice of DWARF format as follows: for the
+32-bit DWARF format, the value is a 32-bit unsigned integer; for the
+64-bit DWARF format, the value is a 64-bit unsigned integer.
+\begin{center}
+\begin{tabular}{lp{6cm}}
+Form & Role \\ \hline
+\DWFORMlinestrp & offset in \dotdebuglinestr
\end{tabular}
\end{center}
\end{longtable}
\end{centering}
+\needlines{5}
\subsubsection{Compilation Unit Header}
\label{datarep:compilationunitheader}
\begin{enumerate}[1. ]
\item \livelinki{chap:classconstant}{constant}{constant class} \\
\livetarg{datarep:classconstant}{}
-There are six forms of constants. There are fixed length
-constant data forms for one, two, four and eight byte values
+There are seven forms of constants. There are fixed length
+constant data forms for one-, two-, four-, eight- and sixteen-byte values
(respectively,
\DWFORMdataoneTARG,
\DWFORMdatatwoTARG,
\DWFORMdatafourTARG,
-and \DWFORMdataeightTARG).
+\DWFORMdataeightTARG{} and
+\DWFORMdatasixteenTARG).
There are also variable length constant
data forms encoded using LEB128 numbers (see below). Both
signed (\DWFORMsdataTARG) and unsigned
\needlines{4}
The data in \DWFORMdataone,
\DWFORMdatatwo,
-\DWFORMdatafour{} and
-\DWFORMdataeight{}
+\DWFORMdatafour{},
+\DWFORMdataeight{} and
+\DWFORMdatasixteen{}
can be anything. Depending on context, it may
be a signed integer, an unsigned integer, a floating\dash point
constant, or anything else. A consumer must use context to
\begin{itemize}
\item \livelinki{chap:classreference}{reference}{reference class} \\
\livetarg{datarep:classreference}{}
-There are three types of reference.
+There are four types of reference.
The
\addtoindexx{reference class}
(\DWFORMrefaddrTARG)
is an offset from the beginning of the
\dotdebuginfo{}
-section of the target executable or shared object;
+section of the target executable or shared object, or, for
+references within a \addtoindex{supplementary object file},
+an offset from the beginning of the local \dotdebuginfo{} section;
it is relocatable in a relocatable object file and frequently
relocated in an executable file or shared object. For
references from one shared object or static executable file
\textit{A debugging information entry that may be referenced by
another compilation unit using
-\DWFORMrefaddr{} must have a
-global symbolic name.}
+\DWFORMrefaddr{} must have a global symbolic name.}
\textit{For a reference from one executable or shared object to
another, the reference is resolved by the debugger to identify
\addtoindexx{type signature}
64\dash bit type signature
(see Section \refersec{datarep:typesignaturecomputation})
-that was computed
-for the type.
+that was computed for the type.
+
+The fourth type of reference is a reference from within the
+\dotdebuginfo{} section of the executable or shared object to
+a debugging information entry in the \dotdebuginfo{} section of
+a \addtoindex{supplementary object file}.
+This type of reference (\DWFORMrefsupTARG) is an offset from the
+beginning of the \dotdebuginfo{} section in the supplementary
+object file.
\textit{The use of compilation unit relative references will reduce the
number of link\dash time relocations and so speed up linking. The
-use of the second and third type of reference allows for the
+use of the second, third and fourth type of reference allows for the
sharing of information, such as types, across compilation
-units.}
+units, while the fourth type further allows for sharing of information
+across compilation units from different executables or shared objects.}
\textit{A reference to any kind of compilation unit identifies the
debugging information entry for that unit, not the preceding
header.}
+\needlines{4}
\item \livelinki{chap:classstring}{string}{string class} \\
\livetarg{datarep:classstring}{}
A string is a sequence of contiguous non\dash null bytes followed by
\addtoindexx{string class}
A string may be represented:
\begin{itemize}
+\setlength{\itemsep}{0em}
\item immediately in the debugging information entry itself
(\DWFORMstringTARG),
+
\item as an
\addtoindexx{section offset!in class string value}
offset into a string table contained in
-the \dotdebugstr{} section of the object file
-(\DWFORMstrpTARG).
+the \dotdebugstr{} section of the object file (\DWFORMstrpTARG),
+the \dotdebuglinestr{} section of the object file (\DWFORMlinestrpTARG),
+or as an offset into a string table contained in the
+\dotdebugstr{} section of a \addtoindex{supplementary object file}
+(\DWFORMstrpsupTARG). \DWFORMstrpNAME{} offsets from the \dotdebuginfo{}
+section of a \addtoindex{supplementary object file}
+refer to the local \dotdebugstr{} section of that same file.
In the \thirtytwobitdwarfformat, the representation of a
\DWFORMstrpNAME{}
value is a 4\dash byte unsigned offset; in the \sixtyfourbitdwarfformat,
it is an 8\dash byte unsigned offset
(see Section \refersec{datarep:32bitand64bitdwarfformats}).
+
\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).
\addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8} attribute is specified for the
compilation, partial, skeleton or type unit entry, string values are encoded using the
UTF\dash 8 (\addtoindex{Unicode} Transformation Format\dash 8) from the Universal
-Character Set standard (ISO/IEC 10646\dash 1:1993). Otherwise,
-the string representation is unspecified.
+Character Set standard (ISO/IEC 10646\dash 1:1993).
+\addtoindexx{ISO 10646 character set standard}
+Otherwise, the string representation is unspecified.
\textit{The \addtoindex{Unicode} Standard Version 3 is fully compatible with
-ISO/IEC 10646\dash 1:1993. It contains all the same characters
+ISO/IEC 10646\dash 1:1993.
+\addtoindexx{ISO 10646 character set standard}
+It contains all the same characters
and encoding points as ISO/IEC 10646, as well as additional
information about the characters and their use.}
of strings; for compatibility, this version also does
not. However, the UTF\dash 8 representation is strongly recommended.}
+\needlines{4}
\item \livelinki{chap:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class} \\
\livetarg{datarep:classstroffsetsptr}{}
This is an offset into the \dotdebugstroffsets{} section
\addtoindexx{call value attribute} \\
\DWATnoreturn~\ddag &0x87 &\CLASSflag
\addtoindexx{noreturn attribute} \\
+\DWATalignment~\ddag &0x88 &\CLASSconstant
+ \addtoindexx{alignment attribute} \\
\DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding} \\
\DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding} \\
\DWFORMflagpresent{} &0x19&\livelink{chap:classflag}{flag} \\
\DWFORMstrx{} \ddag &0x1a&\livelink{chap:classstring}{string} \\
\DWFORMaddrx{} \ddag &0x1b&\livelink{chap:classaddress}{address} \\
-\DWFORMrefsigeight &0x20&\livelink{chap:classreference}{reference} \\
+\DWFORMrefsup{}~\ddag &0x1c &\livelink{chap:classreference}{reference} \\
+\DWFORMstrpsup{}~\ddag &0x1d &\livelink{chap:classstring}{string} \\
+\DWFORMdatasixteen~\ddag &0x1e &\CLASSconstant \\
+\DWFORMrefsigeight &0x20 &\livelink{chap:classreference}{reference} \\
\end{longtable}
\end{centering}
127&127& ---\\
128& 0 + 0x80 & 1 \\
129& 1 + 0x80 & 1 \\
-130& 2 + 0x80 & 1 \\
+%130& 2 + 0x80 & 1 \\
12857& 57 + 0x80 & 100 \\
\end{longtable}
\end{centering}
\addtoindexx{line number opcodes!extended opcode encoding}
Table \refersec{tab:linenumberextendedopcodeencodings}.
+\needlines{20}
\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|c}
\endhead
\hline \emph{Continued on next page}
\endfoot
- \hline \ddag~\textit{New in DWARF Version 5}
+ \hline %\ddag~\textit{New in DWARF Version 5}
\endlastfoot
\DWLNEendsequence &0x01 \\
\DWLNEsetaddress &0x02 \\
-\DWLNEdefinefile &0x03 \\
-\DWLNEsetdiscriminator &0x04 \\
-\DWLNEdefinefileMDfive~\ddag &0x05 \\
+\textit{Reserved} &0x03\footnote{Code 0x03 is reserved to allow backward compatible support of the
+ \texttt{DW\_LNE\_define\_file} operation which was defined prior to \DWARFVersionV.} \\
+\DWLNEsetdiscriminator &0x04 \\
\DWLNElouser &0x80 \\
\DWLNEhiuser &\xff \\
\end{centering}
\needspace{6cm}
-The encodings for the file entry format are given in
+The encodings for the line number header entry formats are given in
\addtoindexx{line number opcodes!file entry format encoding}
-Table \refersec{tab:linenumberfileentryformatencodings}.
+Table \refersec{tab:linenumberheaderentryformatencodings}.
\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|c}
- \caption{Line number file entry format \mbox{encodings}} \label{tab:linenumberfileentryformatencodings}\\
- \hline \bfseries File entry format name&\bfseries Value \\ \hline
+ \caption{Line number header entry format \mbox{encodings}} \label{tab:linenumberheaderentryformatencodings}\\
+ \hline \bfseries Line number header entry format name&\bfseries Value \\ \hline
\endfirsthead
- \bfseries File entry format name&\bfseries Value\\ \hline
+ \bfseries Line number header entry format name&\bfseries Value\\ \hline
\endhead
\hline \emph{Continued on next page}
\endfoot
- \hline
+ \hline \ddag~\textit{New in DWARF Version 5}
\endlastfoot
-
-\DWLNFtimestampsize & 0x01 \\
-\DWLNFMDfive & 0x02 \\
-
+\DWLNCTpath~\ddag & 0x1 \\
+\DWLNCTdirectoryindex~\ddag & 0x2 \\
+\DWLNCTtimestamp~\ddag & 0x3 \\
+\DWLNCTsize~\ddag & 0x4 \\
+\DWLNCTMDfive~\ddag & 0x5 \\
+\DWLNCTlouser~\ddag & 0x2000 \\
+\DWLNCThiuser~\ddag & \xiiifff \\
\end{longtable}
\end{centering}
macro information section are represented as
unsigned LEB128\addtoindexx{LEB128!unsigned} numbers.
+\needlines{4}
The macro information entry type is encoded as a single unsigned byte.
The encodings
\addtoindexx{macro information entry types!encoding}
are given in
Table \refersec{tab:macroinfoentrytypeencodings}.
-\needlines{8}
+\needlines{10}
\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{l|c}
\DWMACROdefineindirect~\ddag &0x05 \\
\DWMACROundefindirect~\ddag &0x06 \\
\DWMACROtransparentinclude~\ddag &0x07 \\
-\textit{Reserved} &0x08-0x0a \\
+\DWMACROdefineindirectsup~\ddag &0x08 \\
+\DWMACROundefindirectsup~\ddag &0x09 \\
+\DWMACROtransparentincludesup~\ddag&0x0a \\
\DWMACROdefineindirectx~\ddag &0x0b \\
\DWMACROundefindirectx~\ddag &0x0c \\
\DWMACROlouser~\ddag &0xe0 \\
that gives the actual length (see
Section \refersec{datarep:32bitand64bitdwarfformats}).
-\needlines{4}
+%\needlines{4}
\item \texttt{version} (\addtoindex{uhalf}) \\
A 2-byte version identifier containing the value
\versiondotdebugstroffsets{}
(see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
+
\item \texttt{padding} (\addtoindex{uhalf}) \\
\end{enumerate}
\versiondotdebugloc{}
(see Appendix \refersec{app:dwarfsectionversionnumbersinformative}).
-\needlines{4}
+\needlines{5}
\item \texttt{address\_size} (\addtoindex{ubyte}) \\
A 1-byte unsigned integer containing the size in
bytes of an address (or the offset portion of an
\dotdebugframe{},
\dotdebuginfo{},
\dotdebugline{},
+\dotdebuglinestr{},
\dotdebugloc{},
\dotdebugmacro{},
\dotdebugpubnames{},
\DWATname,
\DWATaccessibility,
\DWATaddressclass,
+\DWATalignment,
\DWATallocated,
\DWATartificial,
\DWATassociated,
the type that uniquely identifies that type (that is, a different
type is highly unlikely to produce the same string).}
+\needlines{6}
\textit{A debugging information entry should not be placed in a
separate \addtoindex{type unit}
if any of the following apply:}
\textit{This diagram does not distinguish between the normal
and split object section pairs (for example, \dotdebuginfo{}
-versus \dotdebuginfodwo).}
+versus \dotdebuginfodwo). Similarly, it does not show the
+relationship between the main debugging sections of an executable
+or sharable file and a related \addtoindex{supplementary object file}.}
\clearpage
\begin{landscape}
link/.style={rectangle, draw,
inner sep=.2cm, minimum width=4.5cm}]
-% The left column, first sections, then links, from top to bottom
+% The first (leftmost) column, first sections, then links, from top to bottom
%
\node(zsectara) at ( 0, 15.0) [sect] {\dotdebugaranges};
\node(zlinka) at ( 0, 13.5) [link] {To compilation unit~~(a)};
\node(zsectinf) at ( 0, 7.5) [sect] {\begin{tabular}{c}
- \dotdebuginfo
- \end{tabular}};
+ \dotdebuginfo
+ \end{tabular}};
\node(zlinkb) at ( 0, 1.5) [link] {To compilation unit~~(b)};
\node(zsectpub) at ( 0, 0.0) [sect] {\begin{tabular}{c}
- \dotdebugpubnames \\
- \dotdebugpubtypes
- \end{tabular}};
+ \dotdebugpubnames \\
+ \dotdebugpubtypes
+ \end{tabular}};
\draw[thick,-to reversed] (zlinka) -- (zsectara);
\draw[thick,angle 90-] (zsectinf) -- (zlinka);
\draw[thick,-angle 90] (zlinkb) -- (zsectinf);
\draw[thick,to reversed-] (zsectpub) -- (zlinkb);
-% The middle column, similarly
+% The seond column, similarly
%
\node(zsectfra) at (5, 15.0) [sect] {\dotdebugframe};
\node(zlinkc) at (5, 13.5) [link] {To abbreviations~~(c)};
\node(zlinkd) at (5, 12.1) [link] {\DWFORMstrp{}~~(d)};
\node(zlinke) at (5, 10.4) [link] {\begin{tabular}{c}
- \DWATstroffsetsbase \\
- \DWFORMstrx{}~~~~~~~~~(e) \\
- \end{tabular}};
+ \DWATstroffsetsbase \\
+ \DWFORMstrx{}~~~~~~~~~(e) \\
+ \end{tabular}};
\node(zlinkf) at (5, 8.4) [link] {\begin{tabular}{c}
- \DWOPcallref{}~~~~~(f) \\
- \DWFORMrefaddr
- \end{tabular}};
+ \DWOPcallref{}~~~~~(f) \\
+ \DWFORMrefaddr
+ \end{tabular}};
\node(zlinki) at (5, 6.7) [link] {\DWATmacros{}~~(g)};
\node(zlinkj) at (5, 5.4) [link] {\DWATstmtlist{}~~(h)};
\node(zlinkh) at (5, 3.9) [link] {\begin{tabular}{c}
\end{tabular}};
\node(zlinkg) at (5, 2.4) [link] {\DWATlocation{}, etc.~~(j)};
\node(zlinkk) at (5, 0.5) [link] {\begin{tabular}(c)
- \DWATaddrbase \\
- \DWFORMaddrx \\
- \DWOPaddrx \\
- \DWOPconstx
- \end{tabular} (k)};
+ \DWATaddrbase \\
+ \DWFORMaddrx \\
+ \DWOPaddrx \\
+ \DWOPconstx
+ \end{tabular} (k)};
-% Links between left and center
+% Links between first and second columns
%
-\draw[thick,to reversed-] (zsectinf) -- (zlinkc.west);
-\draw[thick,to reversed-] (zsectinf) -- (zlinkd.west);
-\draw[thick,to reversed-] (zsectinf) -- (zlinke.west);
-\draw[<->,thick] (zsectinf) -- (zlinkf.west);
-\draw[thick,to reversed-] (zsectinf) -- (zlinkg.west);
-\draw[thick,to reversed-] (zsectinf) -- (zlinkh.west);
-\draw[thick,to reversed-] (zsectinf) -- (zlinki.west);
-\draw[thick,to reversed-] (zsectinf) -- (zlinkj.west);
-\draw[thick,to reversed-] (zsectinf) -- (zlinkk.north west);
-
-% The right column
+\draw[thick,to reversed-] (zsectinf) -- (zlinkc.west);
+\draw[thick,to reversed-] (zsectinf) -- (zlinkd.west);
+\draw[thick,to reversed-] (zsectinf) -- (zlinke.west);
+\draw[<->,thick] (zsectinf) -- (zlinkf.west);
+\draw[thick,to reversed-] (zsectinf) -- (zlinkg.west);
+\draw[thick,to reversed-] (zsectinf) -- (zlinkh.west);
+\draw[thick,to reversed-] (zsectinf) -- (zlinki.west);
+\draw[thick,to reversed-] (zsectinf) -- (zlinkj.west);
+\draw[thick,to reversed-] (zsectinf) -- (zlinkk.north west);
+
+% The thrid column
%
\node(zsectabb) at (10, 15.00) [sect] {\dotdebugabbrev};
\node(zsectstr) at (10, 13.75) [sect] {\dotdebugstr};
\end{tabular} (o)};
\node(zsectadx) at (10, -0.25) [sect] {\dotdebugaddr{}};
-\draw[thick,to reversed-] (zsectstx) -- (zlinkl);
-\draw[thick,-angle 90] (zlinkl) -- (zsectstr);
+\draw[thick,to reversed-] (zsectstx) -- (zlinkl);
+\draw[thick,-angle 90] (zlinkl) -- (zsectstr);
\draw[thick,to reversed-] (zsectmac) -- (zlinkm);
\draw[thick,-angle 90] (zlinkm) -- (zsectstx);
\draw[thick,to reversed-] (zsectmac) -- (zlinkn);
\draw[thick,to reversed-] (zsectloc) -- (zlinko);
\draw[thick,-angle 90] (zlinko) -- (zsectadx);
-% Links between center and right
+% Links between second and third colums
%
\draw[thick,-angle 90] (zlinkc.east) -- (zsectabb.west);
\draw[thick,-angle 90] (zlinkd.east) -- (zsectstr.west);
\draw[thick,-angle 90] (zlinkj.east) -- (zsectlin.west);
\draw[thick,-angle 90] (zlinkk.east) -- (zsectadx.west);
-\node(zlinky) at (15.5, 10.5) [link] {\begin{tabular}{c}
+% The fourth column
+%
+\node(zlinky) at (15.6, 10.5) [link] {\begin{tabular}{c}
\DWMACROdefineindirect \\
\DWMACROundefindirect \\
(p)
\end{tabular}};
-\node(zlinkz) at (15.5, 6.0) [link] {\begin{tabular}{c}
+\node(zlinkz) at (15.6, 6.0) [link] {\begin{tabular}{c}
\DWMACROtransparentinclude \\
(q)
\end{tabular}};
-
+\node(zlinkx) at (15.6, 3.8) [link] {\DWFORMlinestrp~(r)};
+\node(zsectlns) at (15.6, 2.0) [sect] {\dotdebuglinestr};
+
\draw[thick,to reversed-] (zsectmac.east) -- (zlinky);
\draw[thick,-angle 90] (zlinky) -- (zsectstr.east);
-\draw[<->,thick] (zsectmac.east) -- (zlinkz);
-
+\draw[<->,thick] (zsectmac.east) -- (zlinkz);
+\draw[thick,to reversed-] (zsectlin.east) -- (zlinkx);
+\draw[thick, -angle 90] (zlinkx) -- (zsectlns);
\end{tikzpicture}
\vspace{5mm}
\caption{Debug section relationships}
\dotdebugstroffsets{} section.
%q
+\needlines{4}
\item \dotdebugmacro{} to \dotdebugmacro \\
The second operand of a
\DWMACROtransparentinclude{} macro information
\dotdebugmacro{} section to the header for the
sequence to be transparently included.
+%r
+\item \dotdebugline{} to \dotdebuglinestr \\
+The value of a \DWFORMlinestrp{} form refers to a
+string section specific to the line number table.
+This form can be used in a \dotdebugline{} section
+(as shown) or in a \dotdebuginfo{} section (not shown).
\end{enumerate}
% 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 22, 2014}
+\newcommand{\docdate}{September 25, 2014}
%
\usepackage{ifthen}
\newboolean{isdraft}
\end{table}
}
-% Anti-ligature commands added because \/ and {} don't work for unknown reasons
-% nor does the microtext package DisableLigatures command...???
-%
-\newcommand{\xiiif} {0x3\hspace{1pt}f}
-\newcommand{\xiiifff} {0x3\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f}
-\newcommand{\xff} {0x\hspace{1pt}f\hspace{2pt}f}
-\newcommand{\xffff} {0x\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f\hspace{2pt}f}
-%
-% These are intended for use in running text...
-%
-\newcommand{\xffffffff} {\texttt{0xffffffff}} % use with following punctutation
-\newcommand{\wffffffff} {\texttt{0xffffffff}\ } % use as separate "word"
-\newcommand{\xfffffffzero} {\texttt{0xfffffff0}} % use with following punctutation
-\newcommand{\wfffffffzero} {\texttt{0xfffffff0}\ }
-\newcommand{\xffffffffffffffff} {\texttt{0xffffffffffffffff}} % use with following punctutation
-\newcommand{\wffffffffffffffff} {\texttt{0xffffffffffffffff}\ }
-
% Define commands for all of the DWARF names (DW\_*, .debug_*, a few others)
+%
\include{dwarfnamecmds}
%--- Begin the document pages
\makeevenhead{plain}{}{Change Summary}{}
\makeoddhead{plain}{}{Change Summary}{}
\include{changesummary}
+ \emptypage
}
}{}
-\cleardoublepage
+%\cleardoublepage
\flushleft
\raggedbottom
\chapterstyle{default}
% Define the levels of sectionality that are numbered.
\setcounter{secnumdepth}{5}
-\include{introduction}
-\include{generaldescription} \emptypage
+\include{introduction} \emptypage
+\include{generaldescription} %\emptypage
\include{programscope} %\emptypage
\include{dataobject} \emptypage
-\include{typeentries} %\emptypage
+\include{typeentries} \emptypage
\include{otherdebugginginformation} %\emptypage
\include{datarepresentation} \emptypage
% The \appendix toggles us into appendix chapters
\appendix
-\include{attributesbytag} %\emptypage
-\include{debugsectionrelationships} %\emptypage
+\include{attributesbytag} \emptypage
+\include{debugsectionrelationships} \emptypage
\include{encodingdecoding} \emptypage
\include{examples} %\emptypage
-\include{compression} %\emptypage
-\include{splitobjects} \emptypage
-\include{sectionversionnumbers}
+\include{compression} \emptypage
+\include{splitobjects} %\emptypage
+\include{sectionversionnumbers} \emptypage
\include{gnulicense}
\printindex
\newdwfnamecommands{DWATaccessibility}{DW\_AT\_accessibility}
\newdwfnamecommands{DWATaddrbase}{DW\_AT\_addr\_base}
\newdwfnamecommands{DWATaddressclass}{DW\_AT\_address\_class}
+\newdwfnamecommands{DWATalignment}{DW\_AT\_alignment}
\newdwfnamecommands{DWATallocated}{DW\_AT\_allocated}
\newdwfnamecommands{DWATartificial}{DW\_AT\_artificial}
\newdwfnamecommands{DWATassociated}{DW\_AT\_associated}
\newdwfnamecommands{DWFORMdatatwo}{DW\_FORM\_data2}
\newdwfnamecommands{DWFORMdatafour}{DW\_FORM\_data4}
\newdwfnamecommands{DWFORMdataeight}{DW\_FORM\_data8}
+\newdwfnamecommands{DWFORMdatasixteen}{DW\_FORM\_data16}
\newdwfnamecommands{DWFORMexprloc}{DW\_FORM\_exprloc}
\newdwfnamecommands{DWFORMflag}{DW\_FORM\_flag}
\newdwfnamecommands{DWFORMflagpresent}{DW\_FORM\_flag\_present}
\newdwfnamecommands{DWFORMindirect}{DW\_FORM\_indirect}
-\newdwfnamecommands{DWFORMrefn}{DW\_FORM\_ref<n>} % Generic DW_FORM_ref[1248] name
+\newdwfnamecommands{DWFORMlinestrp}{DW\_FORM\_line\_strp}
+\newdwfnamecommands{DWFORMrefn}{DW\_FORM\_ref<n>} % Generic DW_FORM_ref[1248] name
\newdwfnamecommands{DWFORMrefone}{DW\_FORM\_ref1}
\newdwfnamecommands{DWFORMreftwo}{DW\_FORM\_ref2}
\newdwfnamecommands{DWFORMreffour}{DW\_FORM\_ref4}
\newdwfnamecommands{DWFORMrefeight}{DW\_FORM\_ref8}
\newdwfnamecommands{DWFORMrefaddr}{DW\_FORM\_ref\_addr}
\newdwfnamecommands{DWFORMrefsigeight}{DW\_FORM\_ref\_sig8}
+\newdwfnamecommands{DWFORMrefsup}{DW\_FORM\_ref\_sup}
\newdwfnamecommands{DWFORMrefudata}{DW\_FORM\_ref\_udata}
\newdwfnamecommands{DWFORMsdata}{DW\_FORM\_sdata}
\newdwfnamecommands{DWFORMsecoffset}{DW\_FORM\_sec\_offset}
\newdwfnamecommands{DWFORMstring}{DW\_FORM\_string}
\newdwfnamecommands{DWFORMstrp}{DW\_FORM\_strp}
+\newdwfnamecommands{DWFORMstrpsup}{DW\_FORM\_strp\_sup}
\newdwfnamecommands{DWFORMstrx}{DW\_FORM\_strx}
\newdwfnamecommands{DWFORMudata}{DW\_FORM\_udata}
%
\newdwfnamecommands{DWLLEstartlengthentry}{DW\_LLE\_start\_length\_entry}
\newdwfnamecommands{DWLLEoffsetpairentry}{DW\_LLE\_offset\_pair\_entry}
%
+% DW_LNCT
+%
+\newdwfnamecommands{DWLNCTdirectoryindex}{DW\_LNCT\_directory\_index}
+\newdwfnamecommands{DWLNCTMDfive}{DW\_LNCT\_MD5}
+\newdwfnamecommands{DWLNCTpath}{DW\_LNCT\_path}
+\newdwfnamecommands{DWLNCTsize}{DW\_LNCT\_size}
+\newdwfnamecommands{DWLNCTtimestamp}{DW\_LNCT\_timestamp}
+\newdwfnamecommands{DWLNCTlouser}{DW\_LNCT\_lo\_user}
+\newdwfnamecommands{DWLNCThiuser}{DW\_LNCT\_hi\_user}
+%
% DW_LNE
%
-\newdwfnamecommands{DWLNEdefinefile}{DW\_LNE\_define\_file}
-\newdwfnamecommands{DWLNEdefinefileMDfive}{DW\_LNE\_define\_file\_MD5}
+%\newdwfnamecommands{DWLNEdefinefile}{DW\_LNE\_define\_file}
+%\newdwfnamecommands{DWLNEdefinefileMDfive}{DW\_LNE\_define\_file\_MD5}
\newdwfnamecommands{DWLNEendsequence}{DW\_LNE\_end\_sequence}
\newdwfnamecommands{DWLNEhiuser}{DW\_LNE\_hi\_user}
\newdwfnamecommands{DWLNElouser}{DW\_LNE\_lo\_user}
\newdwfnamecommands{DWMACROdefineindirect}{DW\_MACRO\_define\_indirect}
\newdwfnamecommands{DWMACROundefindirect}{DW\_MACRO\_undef\_indirect}
\newdwfnamecommands{DWMACROtransparentinclude}{DW\_MACRO\_transparent\_include}
+\newdwfnamecommands{DWMACROdefineindirectsup}{DW\_MACRO\_define\_indirect\_sup}
+\newdwfnamecommands{DWMACROundefindirectsup}{DW\_MACRO\_undef\_indirect\_sup}
+\newdwfnamecommands{DWMACROtransparentincludesup}{DW\_MACRO\_transparent\_include\_sup}
\newdwfnamecommands{DWMACROdefineindirectx}{DW\_MACRO\_define\_indirectx}
\newdwfnamecommands{DWMACROundefindirectx}{DW\_MACRO\_undef\_indirectx}
\newdwfnamecommands{DWMACROlouser}{DW\_MACRO\_lo\_user}
\newdwfnamecommands{DWOPand}{DW\_OP\_and}
\newdwfnamecommands{DWOPbitpiece}{DW\_OP\_bit\_piece}
\newdwfnamecommands{DWOPbra}{DW\_OP\_bra}
-\newdwfnamecommands{DWOPbregn}{DW\_OP\_breg<n>} % Generic DW_OP_breg[0..31] name
+\newdwfnamecommands{DWOPbregn}{DW\_OP\_breg<n>} % Generic DW_OP_breg[0..31] name
\newdwfnamecommands{DWOPbregzero}{DW\_OP\_breg0}
\newdwfnamecommands{DWOPbregone}{DW\_OP\_breg1}
\newcommand{\DWOPbregtwo}{\hyperlink{chap:DWOPbregn}{DW\_OP\_breg2}} % Link, don't index...
\newcommand{\dotdebugframe}{\addtoindex{\texttt{.debug\_frame}}}
\newcommand{\dotdebuginfo}{\addtoindex{\texttt{.debug\_info}}}
\newcommand{\dotdebugline}{\addtoindex{\texttt{.debug\_line}}}
+\newcommand{\dotdebuglinestr}{\addtoindex{\texttt{.debug\_line\_str}}}
\newcommand{\dotdebugloc}{\addtoindex{\texttt{.debug\_loc}}}
\newcommand{\dotdebugmacinfo}{\addtoindex{\texttt{.debug\_macinfo}}}
\newcommand{\dotdebugmacro}{\addtoindex{\texttt{.debug\_macro}}}
\newcommand{\dotdebugranges}{\addtoindex{\texttt{.debug\_ranges}}}
\newcommand{\dotdebugstr}{\addtoindex{\texttt{.debug\_str}}}
\newcommand{\dotdebugstroffsets}{\addtoindex{\texttt{.debug\_str\_offsets}}}
+\newcommand{\dotdebugsup}{\addtoindex{\texttt{.debug\_sup}}}
%
\newcommand{\dotdebugabbrevdwo}{\addtoindex{\texttt{.debug\_abbrev.dwo}}}
\newcommand{\dotdebugaddrdwo}{\addtoindex{\texttt{.debug\_addr.dwo}}}
\newcommand{\versiondotdebugpubtypes}{2}
\newcommand{\versiondotdebugranges} {5}
\newcommand{\versiondotdebugstr} {5}
+\newcommand{\versiondotdebugsup} {5}
\newcommand{\versiondotdebugstroffsets}{5}
%
% DWARF Standard Versions
%
\newcommand{\MDfive}{\livelink{def:MDfive}{MD5}}
\newcommand{\COMDAT}{\addtoindex{COMDAT}}
-\newcommand{\autoreturntype}{\texttt{auto} return type\index{auto return type@\texttt{auto} return type}}
\ No newline at end of file
+\newcommand{\autoreturntype}{\texttt{auto} return type\index{auto return type@\texttt{auto} return type}}
+%
+% Anti-ligature commands added because \/ and {} don't work for unknown reasons
+% nor does the microtext package DisableLigatures command...???
+%
+\newcommand{\xiiif} {0x3\hspace{1pt}f}
+\newcommand{\xiiifff} {0x3\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f}
+\newcommand{\xff} {0x\hspace{1pt}f\hspace{2pt}f}
+\newcommand{\xffff} {0x\hspace{1pt}f\hspace{2pt}f\hspace{2pt}f\hspace{2pt}f}
+%
+% These are intended for use in running text...
+%
+\newcommand{\xffffffff} {\texttt{0xffffffff}} % use with following punctutation
+\newcommand{\wffffffff} {\texttt{0xffffffff}\ } % use as separate "word"
+\newcommand{\xfffffffzero} {\texttt{0xfffffff0}} % use with following punctutation
+\newcommand{\wfffffffzero} {\texttt{0xfffffff0}\ }
+\newcommand{\xffffffffffffffff} {\texttt{0xffffffffffffffff}} % use with following punctutation
+\newcommand{\wffffffffffffffff} {\texttt{0xffffffffffffffff}\ }
+
program character_kind
use iso_fortran_env
implicit none
- integer, parameter :: ascii = selected_char_kind ("ascii")
- integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
-
+ integer, parameter :: ascii =
+ selected_char_kind ("ascii")
+ integer, parameter :: ucs4 =
+ selected_char_kind ('ISO_10646')
+\addtoindexx{ISO 10646 character set standard}
character(kind=ascii, len=26) :: alphabet
character(kind=ucs4, len=30) :: hello_world
character (len=*), parameter :: all_digits="0123456789"
file. See Section \refersec{datarep:splitdwarfobjects} and
Appendix \refersec{app:splitdwarfobjectsinformative} for details.
-
+As a further option, debugging information entries and other debugging
+information that are the same in multiple executables or shared objects
+may found in a separate \addtoindex{supplementary object file} that
+contains supplementary debug sections.
+The executable or shared object which contains references to
+those debugging information entries contain a \dotdebugsup{} section
+with information that identifies the supplementary object file; the
+supplementary object file contains a variant of this same section
+that is used to unambiguously associate it with the referencing object.
+
\section{Attribute Types}
\label{chap:attributetypes}
Each attribute value is characterized by an attribute name.
&\livelinki{chap:DWATaddressclasssubroutineorsubroutinetype}{Subroutine or subroutine type}{subroutine or subroutine type} \\
\DWATaddrbaseTARG
&\livelinki{chap:DWATaddrbaseforaddresstable}{Base offset for address table}{address table} \\
+\DWATalignmentTARG
+&\livelinki{chap:DWATalignmentnondefault}{Non-default alignment of type, subprogram or variable}{non-default alignment}
+\addtoindexx{alignment!non-default} \\
\DWATallocatedTARG
&\livelinki{chap:DWATallocatedallocationstatusoftypes}{Allocation status of types}{allocation status of types} \\
\DWATartificialTARG
\DWATspecificationTARG
&\livelinki{chap:DWATspecificationincompletenondefiningorseparatedeclaration}{Incomplete, non-defining, or separate declaration corresponding to a declaration}{incomplete, non-defining, or separate declaration corresponding to a declaration} \\
\DWATstartscopeTARG
-&\livelinki{chap:DWATstartscopeobjectdeclaration}{Object declaration}{object declaration}\\
+&\livelinki{chap:DWATstartscopeobjectdeclaration}{Object declaration}{object declaration}\\*
&\livelinki{chap:DWATstartscopetypedeclaration}{Type declaration}{type declaration}\\
\DWATstaticlinkTARG
&\livelinki{chap:DWATstaticlinklocationofuplevelframe}{Location of uplevel frame}{location of uplevel frame} \\
part of the information that guides the interpretation of a
debugging information entry.
+\needlines{4}
Attribute value forms belong
\addtoindexx{tag names!list of}
to one of the classes shown in Table \referfol{tab:classesofattributevalue}.
\end{enumerate}
-
+\needlines{6}
\subsubsection{Stack Operations}
\label{chap:stackoperations}
The following
debugging information entry in the current compilation unit, which must be a
\DWTAGbasetype{} entry that provides the type of the data pushed.
+\needlines{6}
\itembfnl{\DWOPpushobjectaddressTARG}
The \DWOPpushobjectaddressNAME{}
operation pushes the address
The \DWOPmodTARG{} operation pops the top two stack values and pushes the result of the
calculation: former second stack entry modulo the former top of the stack.
+\needlines{4}
\itembfnl{\DWOPmulTARG}
The \DWOPmulTARG{} operation pops the top two stack entries, multiplies them together, and
pushes the result.
base types, user-defined types and type modifiers.
-
+\needlines{6}
\section{Accessibility of Declarations}
\label{chap:accessibilityofdeclarations}
\textit{Some languages, notably \addtoindex{C++} and
\DWVISqualifiedTARG{} \\
\end{simplenametable}
+\needlines{8}
\section{Virtuality of Declarations}
\label{chap:virtualityofdeclarations}
\textit{\addtoindex{C++} provides for virtual and pure virtual structure or class
that the value corresponds to the default argument for the
template parameter.
-
A
\addtoindexx{formal type parameter|see{template type parameter entry}}
template type parameter entry has a
\DWATtype{} attribute
describing the actual type by which the formal is replaced.
-
A template value parameter entry has a \DWATtype{} attribute
describing the type of the parameterized value.
The entry also has an attribute giving the
Or, the attribute can be a \DWATlocation{} attribute, whose value is a
single location description for the run-time constant address.
+\section{Alignment}
+\label{chap:alignment}
+\livetarg{chap:DWATalignmentnondefault}{}
+A debugging information entry may have a
+\DWATalignment{} 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.)
+
+\textit{Debugging information entries to which \DWATalignment{} may
+apply include (but are not limited to):
+\DWTAGarraytype, \DWTAGatomictype, \DWTAGbasetype,
+\DWTAGclasstype,
+\DWTAGcoarraytype, \DWTAGconsttype, \DWTAGdynamictype,
+\DWTAGenumerationtype, \DWTAGfiletype, \DWTAGinterfacetype,
+\DWTAGpackedtype, \DWTAGpointertype, \DWTAGptrtomembertype,
+\DWTAGreferencetype, \DWTAGrestricttype, \DWTAGrvaluereferencetype,
+\DWTAGsettype, \DWTAGsharedtype, \DWTAGstringtype, \DWTAGstructuretype,
+\DWTAGsubprogram, \DWTAGsubrangetype, \DWTAGsubroutinetype,
+\DWTAGthrowntype, \DWTAGtypedef, \DWTAGuniontype, and \DWTAGvariable.}
+
+
+
Format since Version 4 was published. The list is not meant to be exhaustive.
\begin{itemize}
\item OTHERS TBD...
+\item Add support for collecting common DWARF information (DIEs and macro definitions)
+across multiple executable and shared files and keeping it in a single
+supplementary object file.
+\item Add a string section specific to the line number table (\dotdebuglinestr)
+to more properly support the common practice of stripping all DWARF sections
+except for line number information.
\item Add a split object file and package representations to allow most
DWARF information to be compacted and/or kept separate from an executable
or shared image. This includes new sections
\item Add a new debugging information entry, related attributes and
DWARF expression operators, to describe call information,
including identification of tail calls and tail recursion.
-\item Add a new attribute, \DWATnoreturn{}, to identify a subprogram that
+\item Add a new attribute, \DWATnoreturnNAME{}, to identify a subprogram that
does not return to its caller.
-\item Add a new attribute, \DWATrank{}, to describe the dimensionality of
+\item Add a new attribute, \DWATrankNAME{}, to describe the dimensionality of
an array with dynamic rank.
-\item Add a new tag, \DWTAGgenericsubrange{}, to describe the
+\item Add a new tag, \DWTAGgenericsubrangeNAME{}, to describe the
bounds of Fortran assumed-rank arrays.
\item Add language codes for C 2011, C++ 2003, C++ 2011, Dylan, Go, Haskell,
Julia, Modula 3, Ocaml, Rust, OpenCL and Swift.
DWARF Version 5 is compatible with DWARF Version 4 except as follows:
\begin{itemize}
-\item A new field is included in the line number table header to allow use of an MD5
-hash to validate source file version in use.
-\item New operand forms for attribute values are defined (\DWFORMstrx, \DWFORMaddrx).
+\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
+of directory and file name strings and make provision for vendor-defined
+extensions.
+\item New operand forms for attribute values are defined
+(\DWFORMaddrxNAME, \DWFORMdatasixteenNAME, \DWFORMlinestrpNAME, \DWFORMrefsupNAME,
+\DWFORMstrpNAME, \DWFORMstrpsupNAME, \DWFORMstrxNAME).
(Because a pre-DWARF Version 5 consumer will not be able to interpret these even to
ignore and skip over them, they must be considered incompatible.)
\item A location list entry (see Section \refersec{chap:locationlists}) with
the address range \mbox{(0, \doublequote{-1})} is defined as the new default location
list entry.
-\item In a string type (see Section \refersec{chap:stringtypeentries}), a \DWATbytesize{}
+\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 \DWATstringlength{}
+it described the size of the optional string length data field if the \DWATstringlengthNAME{}
attribute was present.)
\end{itemize}
\item Add support for bundled instructions on machine architectures where instructions do not
occupy a whole number of bytes.
\item Add a new attribute form for
-section offsets, \DWFORMsecoffset,
+section offsets, \DWFORMsecoffsetNAME,
\addtoindexx{section offset}
to replace the use
-of \DWFORMdatafour{} and \DWFORMdataeight{} for section offsets.
-\item Add an attribute, \DWATmainsubprogram, to identify the main subprogram of a
+of \DWFORMdatafourNAME{} and \DWFORMdataeightNAME{} for section offsets.
+\item Add an attribute, \DWATmainsubprogramNAME, to identify the main subprogram of a
program.
\item Define default array lower bound values for each supported language.
\item Add a new technique using separate type units, type signatures and \COMDAT{} sections to
\addtoindex{DWARF Version 3}
consumers because the consumer will not know how to skip over the
unexpected form of data.
-\item DWARF frame and line table sections include a additional fields that affect the location
+\item DWARF frame and line bumber table sections include a additional fields that affect the location
and interpretation of other data in the section.
\end{itemize}
(see Section \refersec{datarep:32bitand64bitdwarfformats}).
\item
References that use the attribute form
-\DWFORMrefaddr{}
+\DWFORMrefaddrNAME{}
are specified to be four bytes in the DWARF 32-bit format and
eight bytes in the DWARF 64-bit format, while
\addtoindex{DWARF Version 2}
Line number information generated for a compilation unit is
represented in the
-\dotdebugline{} section of an object file and
+\dotdebugline{} section of an object file, and optionally
+also in the \dotdebuglinestr{} section, and
is referenced by a corresponding compilation unit debugging
information entry
(see Section \refersec{chap:normalandpartialcompilationunitentries})
-in the \dotdebuginfo{}
-section.
+in the \dotdebuginfo{} section.
\textit{Some computer architectures employ more than one instruction
set (for example, the ARM
\texttt{line} & 1 \\
\texttt{column} & 0 \\
\addttindex{is\_stmt} & determined by \addttindex{default\_is\_stmt}
- in the line number program header \\
+ in the line number program header \\
\addttindex{basic\_block} & \doublequote{false} \addtoindexx{basic block} \\
\addttindex{end\_sequence} & \doublequote{false} \\
\addttindex{prologue\_end} & \doublequote{false} \\
\subsection{The Line Number Program Header}
-
+\label{chap:linenumberprogramheader}
The optimal encoding of line number information depends to a
certain degree upon the architecture of the target machine. The
line number program header provides information used by
the line number information and is independent of the DWARF
version number.
+\item \texttt{address\_size} (ubyte)\\
+A 1-byte unsigned integer containing the size in bytes of an
+address (or offset portion of an address for segmented addressing)
+on the target system.
+
+\textit{The \texttt{address\_size} field is new in DWARF Version 5.
+It is needed to legitimize the common practice of stripping all but
+the line number sections (\dotdebugline{} and \dotdebuglinestr{})
+from an executable.}
+
+\item \texttt{segment\_size} (ubyte) \\
+A 1-byte unsigned integer containing the size in bytes of a segment
+selector on the target system.
+
+\textit{The \texttt{segment\_size} field is new in DWARF Version 5.
+It is needed in combination with the \texttt{address\_size} field (preceding)
+to accurately characterize the address representation on the target
+system.}
+
+\needlines{4}
\item \texttt{header\_length} \\
The number of bytes following the \addttindex{header\_length} field to the
beginning of the first byte of the line number program itself.
\addttindexx{line\_range}
This parameter affects the meaning of the special opcodes. See below.
+\needlines{4}
\item \texttt{opcode\_base} (\addtoindex{ubyte}) \\
The
\addttindexx{opcode\_base}
\textit{Codes for vendor specific extensions, if any, are described
just like standard opcodes.}
-\item \texttt{file\_entry\_format} (\addtoindex{ubyte}) \\
-A format code indicating the format of certain data in the
-entries of the file names field (see below). The format codes
-and their meanings are as follows:
+%%% Save the current enum counter so we can restart later
+%%% End this enumeration so the following text is outdented to
+%%% the left margin (because it applies to the many following
+%%% items
+\newcounter{saveenumi}
+\setcounter{saveenumi}{\value{enumi}}
+\end{enumerate}
+
+\textit{The remaining fields provide information about the
+source files used in the compilation. These fields
+have been revised in \DWARFVersionV{} to support these
+goals:}
\begin{itemize}
-\item \DWLNFtimestampsizeTARG \\
-Entries contain a modification timestamp and file size.
-\item \DWLNFMDfiveTARG \\
-Entries contain an \MDfive{} digest of the file contents.
+\item
+ \textit{To allow new alternative means for a consumer to
+ check that a file it can access is the same version
+ as that used in the compilation.}
+\item
+ \textit{To allow a producer to collect file name strings
+ in a new section (\dotdebuglinestr{}) that can be used
+ to merge duplicate file name strings.}
+\item
+ \textit{To add the ability for producers to provide
+ vendor-defined information that can be skipped by a consumer
+ that is unprepared to process it.}
\end{itemize}
-\needlines{3}
-\item \texttt{include\_directories} (sequence of path names) \\
-Entries
-\addttindexx{include\_directories}
-in this sequence describe each path that was searched
-for included source files in this compilation. (The paths
-include those directories specified explicitly by the user for
-the compiler to search and those the compiler searches without
-explicit direction.) Each path entry is either a full path name
-or is relative to the current directory of the compilation.
-
-The last entry is followed by a single null byte.
-
-The line number program assigns numbers to each of the file
-entries in order, beginning with 1. The current directory of
-the compilation is understood to be the zeroth entry and is
-not explicitly represented.
-
-\item \texttt{file\_names} (sequence of file entries) \\
-Entries
-\addtoindexx{file names}
-in
-\addttindexx{file\_names}
-this sequence describe source files that contribute
-to the line number information for this compilation unit or is
-used in other contexts, such as in a
-\livelinki{chap:declarationcoordinates}{declaration coordinate}{declaration coordinates} or
-a macro file inclusion. Each entry consists of the following
-values:
-
-
-\begin{itemize}
-\item A null\dash terminated string containing the full or relative
-path name of a source file. If the entry contains a file
-name or relative path name, the file is located relative
-to either the compilation directory (as specified by the
-\DWATcompdir{}
-attribute given in the compilation unit) or one
-of the directories listed in the
-\addttindex{include\_directories} section.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned}
-number representing the directory
-index of a directory in the
-\addttindex{include\_directories} section.
-
-\item If \texttt{file\_entry\_format} (see above) is \DWLNFtimestampsize:
+\begin{enumerate}[1. ]
+%%% Resume enumeration count where it left off above
+\setcounter{enumi}{\value{saveenumi}}
+\item \texttt{directory\_entry\_format\_count} (ubyte) \\
+ A count of the number of entries that occur in the
+ following \texttt{directory\_entry\_format} field.
+
+\item \texttt{directory\_entry\_format} (sequence of uleb pairs) \\
+ A sequence of directory entry format descriptions.
+ Each description consists of a pair of uleb values:
\begin{itemize}
- \item An unsigned LEB128\addtoindexx{LEB128!unsigned}
- number representing the
- (implementation-\linebreak[0]defined) time of last modification for
- the file, or 0 if not available.
-
- \item An unsigned LEB128\addtoindexx{LEB128!unsigned}
- number representing the length in
- bytes of the file, or 0 if not available.
+\setlength{\itemsep}{0em}
+\item A content type code (see below)
+\item A form code using the attribute form codes
\end{itemize}
-If \texttt{file\_entry\_format} is \DWLNFMDfive:
+
+\needlines{4}
+\item \texttt{directories\_count} (uleb) \\
+A count of the number of entries that occur in the
+following directories field.
+
+\needlines{4}
+\item \texttt{directories} (sequence of directory names) \\
+A sequence of directory names and optional related
+information. Each entry is encoded as described
+by the \texttt{directory\_entry\_format} field.
+
+Entries in this sequence describe each path that was
+searched for included source files in this compilation,
+including the compilation directory of the compilation.
+(The paths include those directories specified by the
+user for the compiler to search and those the compiler
+searches without explicit direction.)
+
+The first entry is the current directory of the compilation.
+Each additional path entry is either a full path name or
+is relative to the current directory of the compilation.
+
+The line number program assigns a number (index) to each
+of the directory entries in order, beginning with 0.
+
+\textit{Prior to \DWARFVersionV, the current directory was not
+represented in the directories field and a directory index
+of 0 implicitly referred to that directory as found in the
+\DWATcompdir{} attribute of the compilation unit DIE. In
+\DWARFVersionV, the current directory is explicitly present
+in the directories field. This is needed to legitimize the
+common practice of stripping all but the line number sections
+(\dotdebugline{} and \dotdebuglinestr) from an executable.}
+
+\textit{Note that if a \dotdebuglinestr{} section is present,
+both the compilation unit DIE and the line number header can
+share a single copy of the current directory name string.}
+
+\item \texttt{file\_name\_entry\_format\_count} (ubyte) \\
+A count of the number of file entry format entries that
+occur in the following \texttt{file\_name\_entry\_format} field.
+If this field is zero, then the \texttt{file\_names\_count} field
+(see below) must also be zero.
+
+\item \texttt{file\_name\_entry\_format} (sequence of uleb pairs) \\
+A sequence of file entry format descriptions.
+Each description consists of a pair of uleb values:
\begin{itemize}
-\item A 16-byte \MDfive{} digest of the file contents.
+\setlength{\itemsep}{0em}
+\item A content type code (see below)
+\item A form code using the attribute form codes
\end{itemize}
-\end{itemize}
+\item \texttt{file\_names\_count} (uleb) \\
+A count of the number of file name entries that occur
+in the following \texttt{file\_names} field.
-The last entry is followed by a single null byte.
+\needlines{4}
+\item \texttt{file\_names} (sequence of file name entries) \\
+A sequence of file names and optional related
+information. Each entry is encoded as described
+by the \texttt{file\_name\_entry\_format} field (in the
+order described).
+
+Entries in this sequence describe source files that
+contribute to the line number information for this
+compilation or is used in other contexts, such as in
+a declaration coordinate or a macro file inclusion.
+
+The first entry in the sequence is the primary source file
+whose file name exactly matches that given in the
+\DWATname{} attribute in the compilation unit DIE.
+
+The line number program assigns numbers to each of
+the file name entries in order, beginning with 0, and uses
+those numbers instead of file names in the line number
+program that follows.
+
+\textit{Prior to \DWARFVersionV, the current compilation
+file name was not represented in the \texttt{file\_names}
+field. In \DWARFVersionV, the current compilation file name
+is explicitly present and has index 0. This is needed to legitimize
+the common practice of stripping all but the line number sections
+(\dotdebugline{} and \dotdebuglinestr) from an executable.}
-The directory index represents an entry in the
-\addttindex{include\_directories} section.
-The index is 0 if the file was
-found in the current directory of the compilation, 1 if it
-was found in the first directory in the
-\addttindex{include\_directories}
-section, and so on. The directory index is ignored for file
-names that represent full path names.
+\end{enumerate}
-The primary source file is described by an entry whose path
-name exactly matches that given in the \DWATname{} attribute
-in the compilation unit, and whose directory is understood
-to be given by the implicit entry with index 0.
+\subsubsubsection{Standard Content Descriptions}
+DWARF-defined content type codes are used to indicate
+the type of information that is represented in one
+component of an include directory or file name description.
+The following type codes are defined.
+\begin{enumerate}[1. ]
-The line number program assigns numbers to each of the file
-entries in order, beginning with 1, and uses those numbers
-instead of file names in the file register.
+\item \DWLNCTpathTARG \\
+The component is a null-terminated path name string.
+If the associated form code is \DWFORMstring{}, then the
+string occurs immediately in the containing \texttt{directories}
+or \texttt{file\_names} field. If the form code is \DWFORMlinestrp{},
+then the string is included in the \dotdebuglinestr{} section
+and its offset occurs immediately in the containing
+\texttt{directories} or \texttt{file\_names} field.
+
+\textit{Note that this use of \DWFORMlinestrp{} is similar to
+\DWFORMstrp{} but refers to the \dotdebuglinestr{} section,
+not \dotdebugstr.}
+
+In a \dotdebuglinedwo{} section, the form \DWFORMstrx{} may
+also be used. This refers into the \dotdebugstroffsetsdwo{}
+section (and indirectly also the \dotdebugstrdwo{} section)
+because no \texttt{.debug\_line\_str\_offsets.dwo} or
+\texttt{.debug\_line\_str.dwo} sections exist or are defined for
+use in split objects. (The form \DWFORMstring{} may also be used,
+but this precludes the benefits of string sharing.)
+
+In the 32-bit DWARF format, the representation of a
+\DWFORMlinestrp{} value is a 4-byte unsigned offset; in the
+64-bit DWARF format, it is an 8-byte unsigned offset (see
+Section \refersec{datarep:32bitand64bitdwarfformats}).
+
+\item \DWLNCTdirectoryindexTARG \\
+The unsigned directory index represents an entry in the
+directories field of the header. The index is 0 if
+the file was found in the current directory of the compilation
+(hence, the first directory in the directories field),
+1 if it was found in the second directory in the directories
+field, and so on.
+
+This content code is always paired with one of \DWFORMdataone,
+\DWFORMdatatwo{} or \DWFORMudata.
+
+\textit{The optimal form for a producer to use (which results in the
+minimum size for the set of \texttt{include\_index} fields) depends not only
+on the number of directories in the directories
+field, but potentially on the order in which those directories are
+listed and the number of times each is used in the \texttt{file\_names} field.
+However, \DWFORMudata{} is expected to be near optimal in most common
+cases.}
+
+\item \DWLNCTtimestampTARG \\
+\DWLNCTtimestampNAME{} indicates that the value is the implementation-defined
+time of last modification of the file, or 0 if not available.
+It is always paired with one of the forms
+\DWFORMudata, \DWFORMdatafour, \DWFORMdataeight{} or \DWFORMblock.
+
+\item \DWLNCTsizeTARG \\
+\DWLNCTsizeNAME{} indicates that the value is the unsigned size of the
+file in bytes, or 0 if not available. It is paired with one of the
+forms \DWFORMudata, \DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour{}
+or \DWFORMdataeight.
+
+\item \DWLNCTMDfiveTARG \\
+\DWLNCTMDfiveNAME{} indicates that the value is a 16-byte \MDfive digest
+of the file contents. It is paired with form \DWFORMdatasixteen.
+\end{enumerate}
-\textit{A compiler may generate a single null byte for the file
-names field and define file names using the extended opcode
-\DWLNEdefinefile{} (when \texttt{file\_entry\_format} is \DWLNFtimestampsize) or
-\DWLNEdefinefileMDfive{} (when \texttt{file\_entry\_format} is \DWLNFMDfive).}
+\textit{Using this representation, the information found in a DWARF
+Version 4 line number header could be encoded as shown in
+Figure \refersec{fig:preV5LNCTusingV5}.}
+\begin{figure}[here]
+\begin{dwflisting}
+\begin{alltt}
+ Field Field Name Value(s)
+ Number
+ 1 \textit{Same as in Version 4} ...
+ 2 version 5
+ 3 \textit{Not present in Version 4} -
+ 4 \textit{Not present in Version 4} -
+ 5-12 \textit{Same as in Version 4} ...
+ 13 directory_entry_format_count 1
+ 14 directory_entry_format \DWLNCTpath, \DWFORMstring
+ 15 directories_count <n>
+ 16 directories <n>*<null terminated string>
+ 17 file_name_entry_format_count 4
+ 18 file_name_entry_format \DWLNCTpath, \DWFORMstring,
+ \DWLNCTdirectoryindex, \DWFORMudata,
+ \DWLNCTtimestamp, \DWFORMudata,
+ \DWLNCTsize, \DWFORMudata
+ 19 file_names_count <m>
+ 20 file_names <m>*{<null terminated string>,
+ <index>, <timestamp>, <size>}
+\end{alltt}
+\end{dwflisting}
+\caption{Pre-\DWARFVersionV{} Line Number Program Header Information \mbox{Encoded} Using \DWARFVersionV}
+\label{fig:preV5LNCTusingV5}
+\end{figure}
-\end{enumerate}
+\subsubsubsection{Vendor-defined Content Descriptions}
+Vendor-defined content descriptions may be defined using content
+type codes in the range \DWLNCTlouserTARG{} to \DWLNCThiuserTARG{}. Each
+such code may be combined with one or more forms from the set:
+\DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
+\DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight,
+\DWFORMdatasixteen,
+\DWFORMflag, \DWFORMlinestrp, \DWFORMsdata, \DWFORMsecoffset,
+\DWFORMstring, \DWFORMstrp, \DWFORMstrx{} and \DWFORMudata.
-\subsection{The Line Number Program}
+If a consumer encounters a vendor-defined content type that
+it does not understand, it should skip the content data as though
+it was not present.
+\subsection{The Line Number Program}
+\label{linenumberprogram}
As stated before, the goal of a line number program is to build
a matrix representing one compilation unit, which may have
produced multiple sequences of target machine instructions.
affect the \texttt{address} register add a delta to it. This instruction
stores a relocatable value into it instead.}
-\needlines{4}
-\item \textbf{\DWLNEdefinefileTARG} \\
-The \DWLNEdefinefileTARG{} opcode takes four operands:
-\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
-name or a relative path name, the file is located relative
-to either the compilation directory (as specified by the
-\DWATcompdir{} attribute given in the compilation unit)
-or one of the directories in the
-\addttindex{include\_directories} section.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned}
-number representing the directory index
-of the directory in which the file was found.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned}
-number representing the time of last modification
-of the file, or 0 if not available.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned}
-number representing the length in bytes of the file, or 0 if
-not available.
-\end{enumerate}
-
-The directory index represents an entry in the
-\addttindex{include\_directories} section of the line number program
-header. The index is 0 if the file was found in the current
-directory of the compilation, 1 if it was found in the first
-directory in the \addttindex{include\_directories} section,
-and so on. The
-directory index is ignored for file names that represent full
-path names.
-
-The primary source file is described by an entry whose path
-name exactly matches that given in the \DWATname{} attribute
-in the compilation unit, and whose directory index is 0. The
-files are numbered, starting at 1, in the order in which they
-appear; the names in the header come before names defined by
-the \DWLNEdefinefile{} instruction. These numbers are used
-in the file register of the state machine.
-
\item \textbf{\DWLNEsetdiscriminatorTARG} \\
The \DWLNEsetdiscriminatorTARG{}
opcode takes a single
integer. It sets the
\addttindex{discriminator} register to the new value.
-\needlines{4}
-\item \textbf{\DWLNEdefinefileMDfiveTARG} \\
-The \DWLNEdefinefileMDfiveTARG{} opcode takes three operands:
-\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
-name or a relative path name, the file is located relative
-to either the compilation directory (as specified by the
-\DWATcompdir{} attribute given in the compilation unit)
-or one of the directories in the
-\addttindex{include\_directories} section.
-
-\item An unsigned LEB128\addtoindexx{LEB128!unsigned}
-number representing the directory index
-of the directory in which the file was found.
-
-\item A 16-byte \MDfive{} digest of the file contents.
-\end{enumerate}
-The first two operands are interpreted in the same way as the
-first two operands of \DWLNEdefinefile.
\end{enumerate}
+\textit{The \texttt{DW\_LNE\_define\_file} operation defined
+in earlier versions of DWARF is deprecated in \DWARFVersionV.}
+\addtoindexx{\texttt{DW\_LNE\_define\_file}!deprecated}
+
\textit{Appendix \refersec{app:linenumberprogramexample}
gives some sample line number programs.}
the operand is encoded. The allowed forms are:
\DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
\DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight,
-\DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
+\DWFORMdatasixteen, \DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
\DWFORMstring, \DWFORMstrp{} and \DWFORMstrx.
\end{enumerate}
\subsection{Macro Information Entries}
\label{chap:macroinformationentries}
-The following kinds of macro information entries are defined:
-
-\begin{tabular}{ll}
+The kinds of macro information entries are shown in Table \refersec{tab:macroinformationentrykinds}.
+\begin{table}[here]
+\centering
+\caption{Macro information entry kinds}
+\label{tab:macroinformationentrykinds}
+\begin{tabular}{l|p{7cm}}
+\hline
+Name&Meaning\\ \hline
\DWMACROdefine{} &A macro definition\\
\DWMACROundef &A macro undefinition\\
\DWMACROstartfile &The start of a new source file inclusion\\
-\DWMACROendfile &The end of the current source file inclusion\\
+\DWMACROendfile &The end of the current source file \mbox{inclusion}\\
\DWMACROdefineindirect &A macro definition (indirect name string)\\
\DWMACROundefindirect &A macro undefinition (indirect name string)\\
-\DWMACROtransparentinclude &A sequence of macro information entries to include\\
+\DWMACROtransparentinclude &A sequence of macro information \mbox{entries} to include\\
+\DWMACROdefineindirectsup &A macro definition whose indirect name string is in the
+ \addtoindex{supplementary object file}\\
+\DWMACROundefindirectsup &A macro undefinition whose indirect name string is in the
+ supplementary object file)\\
+\DWMACROtransparentincludesup
+ &A sequence of macro information \mbox{entries} to include
+ from the \addtoindex{supplementary object file}\\
\DWMACROdefineindirectx &A macro definition (indexed name string)\\
\DWMACROundefindirectx &A macro undefinition (indexed name string)\\
+\hline
\end{tabular}
+\end{table}
\subsubsection{Define and Undefine Entries}
\label{chap:defineandundefineentries}
these entries are equivalent to \DWMACROdefine{}
and \DWMACROundef.
+\subsubsubsection{Define and Undefine Using Indirect Strings in a Supplementary Object File}
+A \DWMACROdefineindirectsupTARG{} or \DWMACROundefindirectsupTARG{} entry has
+two operands. The first operand encodes the line number of the source line
+on which the relevant defining or undefining macro directives appeared.
+The second operand consists of an offset into a string table contained in
+the \dotdebugstr{} section of the \addtoindex{supplementary object file}.
+The size of the operand is given in the section header \texttt{offset\_size} field.
+Apart from the encoding of the second operand these entries are equivalent to
+\DWMACROdefineindirect{} and \DWMACROundefindirect{}, respectively.
+
+
+
\subsubsection{Start File Entries}
\label{chap:startfileentries}
A \DWMACROstartfileTARG{} entry has two operands. The
the entry marks the end of the current source file inclusion.
\subsubsection{Transparent Inclusion of a Sequence of Entries}
+\textit{The transparent inclusion entry types makes it possible
+to share duplicate sequences of macro information entries among different
+compilation units or object files.}
+
+\subsubsubsection{Transparent Inclusion within the Current Compilation}
A \DWMACROtransparentincludeTARG{} entry has one operand, an offset into
another part of the \dotdebugmacro{} section. The size of the operand
is given in the header \texttt{offset\_size} field. The
\dotdebugmacro{} offset, up to, but excluding,
the terminating entry with opcode \texttt{0}.
-\textit{The \DWMACROtransparentincludeNAME{} entry type makes it possible
-to share duplicate sequences of macro information entries among different
-compilation units.}
+\subsubsubsection{Transparent Inclusion Across Executable and Shared Object Files}
+A \DWMACROtransparentincludesupTARG{} entry has one operand, an
+offset from the start of the \dotdebugmacro{} section in the
+\addtoindex{supplementary object file}.
+The size of the operand is given in the section header offset size.
+Apart from the different location in which to find the sequence of
+macro information entries this entry type is equivalent to
+\DWMACROtransparentinclude. This entry type is aimed at sharing duplicate
+sequences of macro information entries between \dotdebugmacro{}
+sections from different executables or shared objects.
+
+\needlines{4}
+From within the \dotdebugmacro{} section of the \addtoindex{supplementary object file},
+\DWMACROdefineindirect{} and \DWMACROundefindirect{} entry types refer to the
+local \dotdebugstr{} section and \DWMACROtransparentinclude{} refers to the
+local \dotdebugmacro{} section.
+
\needlines{4}
\subsection{Base Source Entries}
\addtoindexx{use UTF8 attribute}\addtoindexx{UTF-8}
which is a \livelink{chap:classflag}{flag} whose
presence indicates that all strings (such as the names of
-declared entities in the source program, or file names in the line table)
+declared entities in the source program, or filenames in the line number table)
are represented using the UTF\dash 8 representation.
\item A \DWATmainsubprogram{} attribute, which is a \livelink{chap:classflag}{flag}
\item Template parameters are described and referenced as specified in
Section \refersec{chap:templateparameters}.
+\needlines{4}
\item If the compiler has generated a special compilation unit
to hold the template instantiation and that compilation unit
has a different name from the compilation unit containing
entry with the tag \DWTAGsubprogram. Such an entry has a
\DWATinline{} attribute whose value is \DWINLinlined.}
-
+\needlines{4}
\subsubsection{Abstract Instances}
\label{chap:abstractinstances}
Any debugging information entry that is owned (either
A \textit{tail recursion call} is a call
to the current subroutine which is compiled as a loop into the middle of the
current subroutine.
+\needlines{4}
\item
An \textit{inline (or inlined) call} is a call to an inlined subprogram,
where at least one instruction has the location of the inlined subprogram
\DWTAGvariable{}, \DWTAGformalparameter{} or \DWTAGmember{} entry representing
the subroutine pointer that is called.
+\needlines{4}
The call site may have a
\DWATcalltargetNAME{}
\livetargi{chap:DWATcalltargetofcallsite}{attribute}{call target attribute} which is
address of the subprogram that will be called. The DWARF expression should
not use register or memory locations that might be clobbered by the call.
+\needlines{4}
The call site entry may have a
\DWATcalltargetclobberedNAME{}
\livetargi{chap:DWATcalltargetclobberedofcallsite}{attribute}{call target clobbered attribute}
Table \refersec{tab:sectionversionnumbers}
shows what version
-numbers are in use for each section.
+numbers are in use for each section. In that table:
+\begin{itemize}
+\setlength{\itemsep}{0em}
+\item \doublequote{V2} means \addtoindex{DWARF Version 2}, published July 27, 1993.
+\item \doublequote{V3} means \addtoindex{DWARF Version 3}, published December 20, 2005.
+\item \doublequote{V4} means \addtoindex{DWARF Version 4}, published June 10, 2010.
+\item \doublequote{V5} means \addtoindex{DWARF Version 5}\footnote{Higher numbers are reserved for future use.}, published
+ \ifthenelse{\boolean{isdraft}}{\textit{<to be determined>}}{\docdate}.
+\end{itemize}
There are sections with no version number encoded in them;
they are only accessed via the
format would be represented by a change in the
\dotdebuginfo{} section version number.
+\needlines{10}
\begin{centering}
\setlength{\extrarowheight}{0.1cm}
\begin{longtable}{lcccc}
\caption{Section version numbers} \label{tab:sectionversionnumbers} \\
- \hline \bfseries Section Name &\bfseries V2 &\bfseries V3 &\bfseries V4 &\bfseries V5 \\ \hline
+ \hline
+ \bfseries Section Name &\bfseries V2 &\bfseries V3 &\bfseries V4
+ &\bfseries V5 \\
+ \hline
\endfirsthead
\bfseries Section Name &\bfseries V2 &\bfseries V3 &\bfseries V4 &\bfseries V5 \\ \hline
\endhead
& 1 & 3 & 4 & 4 \\
\dotdebuginfo{} & 2 & 3 & 4 & 5 \\
\dotdebugline{} & 2 & 3 & 4 & 5 \\
+\dotdebuglinestr{} & - & - & - & 5 \\
\dotdebugloc{} & * & * & * & 5 \\
\dotdebugmacinfo{} & * & * & * & - \\*
\dotdebugmacro{} & - & - & - & 5 \\
\dotdebugranges{} & - & * & * & 5 \\
\dotdebugstr{} & * & * & * & * \\
\dotdebugstroffsets & - & - & - & 5 \\
+\dotdebugsup & - & - & - & 5 \\
\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (Version 4)}
& - & - & 4 & - \\
\hspace{3.5cm}\textit{(.dwp sections)}\\
\dotdebugcuindex{} & - & - & - & 5 \\
\dotdebugtuindex{} & - & - & - & 5 \\
-
\end{longtable}
\end{centering}
+\needlines{8}
Notes:
-
\begin{itemize}
-\item \doublequote{V2} means \addtoindex{DWARF Version 2}, published July 27, 1993.
-\item \doublequote{V3} means \addtoindex{DWARF Version 3}, published December 20, 2005.
-\item \doublequote{V4} means \addtoindex{DWARF Version 4}, published June 10, 2010.
-\item \doublequote{V5} means \addtoindex{DWARF Version 5}, published
- \ifthenelse{\boolean{isdraft}}{\textit{<to be determined>}}{\docdate}.
\item \doublequote{*} means that a version number is not applicable
(the section does not include a header or the section's header does not include a version).
-
\item \doublequote{-} means that the section was not defined in that
version of the DWARF standard.
-
\item The version numbers for corresponding .debug\_<kind> and .debug\_<kind>.dwo
sections are the same.
-
\end{itemize}
-Higher numbers are reserved for future use.
+
\dotdebugmacrodwo{} - Contains macro definition information,
normally found in the \dotdebugmacro{} section.
\item
-\dotdebuglinedwo{} - Contains skeleton line tables for the type
-units in the \dotdebuginfodwo{} section. These line tables
-contain only the directory and files lists needed to
+\dotdebuglinedwo{} - Contains skeleton line number tables for the type
+units in the \dotdebuginfodwo{} section. These tables
+contain only the directory and filename lists needed to
interpret \DWATdeclfile{} attributes in the debugging
information entries. Actual line number tables remain in the
\dotdebugline{} section, and remain in the relocatable object
(.o) files.
+
+In a .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
+directory and file name strings to be merged with general
+strings and across compilations in package files (which are not
+subject to potential stripping).
+
\end{itemize}
In order for the consumer to locate and process the debug
\DWATEsignedfixedTARG{} & signed fixed\dash point scaled integer \\
\DWATEunsignedfixedTARG& unsigned fixed\dash point scaled integer \\
\DWATEdecimalfloatTARG{} & decimal floating\dash point number \\
-\DWATEUTFTARG{} & \addtoindex{Unicode} character \\
-\DWATEASCIITARG{} & \addtoindex{ASCII} character \\
-\DWATEUCSTARG{} & \addtoindex{ISO 10646} character \\
+\DWATEUTFTARG{} & \addtoindexi{Unicode character}{Unicode character base type} \\
+\DWATEASCIITARG{} & \addtoindexi{ASCII character}{ASCII character base type}\\
+\DWATEUCSTARG{} & \addtoindexi{ISO 10646 character}{ISO 10646 character base type}
+ \addtoindexx{ISO 10646 character set standard} \\
\hline
\end{tabular}
\end{table}
\textit{The \DWATEUTF{} encoding is intended for \addtoindex{Unicode}
string encodings (see the Universal Character Set standard,
-ISO/IEC 10646\dash 1:1993). For example, the
+ISO/IEC 10646\dash 1:1993).
+ \addtoindexx{ISO 10646 character set standard}
+For example, the
\addtoindex{C++} type char16\_t is
represented by a base type entry with a name attribute whose
value is \doublequote{char16\_t}, an encoding attribute whose value
is \DWATEUTF{} and a byte size attribute whose value is 2.}
\textit{The \DWATEASCII{} and \DWATEUCS{} encodings are intended for
-the {Fortran 2003} string kinds \texttt{ASCII} (ISO/IEC 646:1991) and
-\texttt{ISO\_10646} (UCS-4 in ISO//IEC 10646:2000).}
+the {Fortran 2003} string kinds
+\texttt{ASCII}\index{ASCII@\texttt{ASCII} (Fortran string kind)} (ISO/IEC 646:1991) and
+\texttt{ISO\_10646}\index{ISO\_10646@\texttt{ISO\_10646} (Fortran string kind)} (UCS-4 in ISO/IEC 10646:2000).}
+\addtoindexx{ISO 10646 character set standard}
The
\DWATEpackeddecimal{}
\addtoindex{Fortran 2003} language standard allows string
types that are composed of different types of (same sized) characters.
While there is no standard list of character kinds, the kinds
-\addttindex{ASCII} (see \DWATEASCII), \addttindex{ISO\_10646}
-(see \DWATEUCS) and \texttt{DEFAULT} are defined.}
+\texttt{ASCII}\index{ASCII@\texttt{ASCII} (Fortran string kind)} (see \DWATEASCII),
+\texttt{ISO\_10646}\index{ISO\_10646@\texttt{ISO\_10646} (Fortran string kind)}
+\addtoindexx{ISO 10646 character set standard}
+(see \DWATEUCS) and
+\texttt{DEFAULT}\index{DEFAULT@\texttt{DEFAULT} (Fortran string kind)}
+are defined.}
A string type entry may have a \DWATtype{}
\livetargi{char:DWAATtypeofstringtype}{attribute}{type attribute!of string type entry}
DWARF Git Projects / dwarf-doc.git / commitdiff