review comments to date.
Signed-off-by: Ron Brender <ron.brender@gmail.com>
\begin{longtable}{ll}
\textbf{Date} & \textbf{Issue Incorporated or Other Change} \\ \hline \\
\endhead
+6/17/2014 & 140506.1 (correct DWARF error in member function example), \\
+ & 140602.1 (Swift language), 140606.1 (Julia language), \\
+ & 140421.1 (DWARF package files), all review comments to date \\
+6/16/2014 & 100805.1 (correct/update reference item description) \\
+6/15/2014 & Fix lingering hyperlink problems found by updated refer.py \\
+ & 110110.1 \& 130623.1 (add example), 121221.1 (add example) \\
5/21/2014 & 121221.1 (character kinds for Fortran, w/o example) \\
5/16/2014 & 140227.1 (references to within type unit), Walker review comments, \\
& 140331.1 (noreturn attribute) \\
-\section{Relocatable, Split, Executable and Shared Objects}
+\section{Relocatable, Split, Executable, Shared and Package Object Files}
\label{datarep:executableobjectsandsharedobjects}
\subsection{Relocatable Objects}
base address at which the object was attached. This offset
is available in the run\dash time linker\textquoteright s data structures.}
+\subsection{DWARF Package Files}
+\label{datarep:dwarfpackagefiles}
+\textit{Using split DWARF objects allows the developer to compile,
+link, and debug an application quickly with less link-time overhead,
+but a more convenient format is needed for saving the debug
+information for later debugging of a deployed application. A
+DWARF package file can be used to collect the debugging
+information from the object (or separate DWARF object) files
+produced during the compilation of an application.}
+
+\textit{The package file is typically placed in the same directory as the
+application, and is given the same name with a \doublequote{\texttt{.dwp}}
+extension.\addtoindexx{\texttt{.dap} file extension}}
+
+A DWARF package file is itself an object file, using the
+\addtoindexx{package files}
+\addtoindexx{DWARF package files}
+same object file format, byte order, and size as the
+corresponding application binary. It consists only of a file
+header, section table, a number of DWARF debug information
+sections, and two index sections.
+
+Each DWARF package file contains no more than one of each of the
+following sections, copied from a set of object or DWARF object
+files, and combined, section by section:
+\begin{alltt}
+ \dotdebuginfodwo
+ \dotdebugabbrevdwo
+ \dotdebuglinedwo
+ \dotdebuglocdwo
+ \dotdebugstroffsetsdwo
+ \dotdebugstrdwo
+ \dotdebugmacrodwo
+\end{alltt}
+
+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
+contribution to the \dotdebugstroffsetsdwo{} section, which in turn
+will provide the offset of a string in the \dotdebugstrdwo{}
+section.
+
+The DWARF package file also contains two index sections that
+provide a fast way to locate debug information by compilation
+unit signature (\DWATdwoid) for compilation units, or by type
+signature for type units:
+\begin{alltt}
+ \dotdebugcuindex
+ \dotdebugtuindex
+\end{alltt}
+
+\subsubsection{The Compilation Unit (CU) Index Section}
+The \dotdebugcuindex{} section is a hashed lookup table that maps a
+compilation unit signature to a set of contributions in the
+various debug information sections. Each contribution is stored
+as an offset within its corresponding section and a size.
+
+Each compilation unit set may contain contributions from the
+following sections:
+\begin{alltt}
+ \dotdebuginfodwo{} (required)
+ \dotdebugabbrevdwo{} (required)
+ \dotdebuglinedwo
+ \dotdebuglocdwo
+ \dotdebugstroffsetsdwo
+ \dotdebugmacrodwo
+\end{alltt}
+
+\textit{Note that a set is not able to represent \dotdebugmacinfo{}
+information from \DWARFVersionIV{} or earlier formats.}
+
+\subsubsection{The Type Unit (TU) Index Section}
+The \dotdebugtuindex{} section is a hashed lookup table that maps a
+type signature to a set of offsets into the various debug
+information sections. Each contribution is stored as an offset
+within its corresponding section and a size.
+
+Each type unit set may contain contributions from the following
+sections:
+\begin{alltt}
+ \dotdebuginfodwo{} (required)
+ \dotdebugabbrevdwo{} (required)
+ \dotdebuglinedwo
+ \dotdebugstroffsetsdwo
+\end{alltt}
+
+\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.
+Each section begins with a header, followed by a hash table of
+signatures, a parallel table of indexes, a table of offsets, and
+a table of sizes. The index sections are aligned at 8-byte
+boundaries in the file.
+
+\needlines{6}
+The index section header contains four unsigned 32-bit values
+(using the byte order of the application binary):
+\begin{itemize}
+\item The \addtoindexi{version number}{version number!package index tables}
+ of the format of this index (currently 5)
+\item L, the number of columns in the table of section offsets
+\item N, the number of compilation units or type units in the index
+\item M, the number of slots in the hash table
+\end{itemize}
+
+\textit{We assume that N and M will not exceed $2^{32}$.}
+
+The size of the hash table, M, must be $2^k$ such that:
+\hspace{0.3cm}$2^k\ \ >\ \ 3*N/2$
+
+The hash table begins at offset 16 in the section, and consists
+of an array of M 64-bit slots. Each slot contains a 64-bit
+signature (using the byte order of the application binary).
+
+The parallel table begins immediately after the hash table (at
+offset \mbox{16 + 8 * M} from the beginning of the section), and
+consists of an array of M 32-bit slots (using the byte order of
+the application binary), corresponding 1-1 with slots in the hash
+table. Each entry in the parallel table contains a row index into
+the tables of offsets and sizes.
+
+Unused slots in the hash table have 0 in both the hash table
+entry and the parallel table entry. While 0 is a valid hash
+value, the row index in a used slot will always be non-zero.
+
+Given a 64-bit compilation unit signature or a type signature S,
+an entry in the hash table is located as follows:
+\begin{enumerate}[1. ]
+\item Calculate a primary hash $H = S\ \&\ MASK(k)$, where $MASK(k)$ is a
+ mask with the low-order k bits all set to 1.
+
+\item Calculate a secondary hash $H' = (((S>>32)\ \&\ MASK(k))\ |\ 1)$.
+
+\item If the hash table entry at index H matches the signature, use
+ that entry. If the hash table entry at index H is unused (all
+ zeroes), terminate the search: the signature is not present
+ in the table.
+
+\item Let $H = (H + H')\ modulo\ M$. Repeat at Step 3.
+\end{enumerate}
+
+Because $M > N$, and H' and M are relatively prime, the search is
+guaranteed to stop at an unused slot or find the match.
+
+\needlines{4}
+The table of offsets begins immediately following the parallel
+table (at offset \mbox{16 + 12 * M} from the beginning of the section).
+The table is a two-dimensional array of 32-bit words (using the
+byte order of the application binary), with L columns and N+1
+rows, in row-major order. Each row in the array is indexed
+starting from 0. The first row provides a key to the columns:
+each column in this row provides an identifier for a debug
+section, and the offsets in the same column of subsequent rows
+refer to that section. The section identifiers are shown in
+Table \referfol{tab:dwarfpackagefilesectionidentifierencodings}.
+
+\begin{centering}
+\setlength{\extrarowheight}{0.1cm}
+\begin{longtable}{l|c|l}
+ \caption{DWARF package file section identifier \mbox{encodings}}
+ \label{tab:dwarfpackagefilesectionidentifierencodings}
+ \addtoindexx{DWARF package files!section identifier encodings} \\
+ \hline \bfseries Section identifier &\bfseries Value &\bfseries Section \\ \hline
+\endfirsthead
+ \bfseries Section identifier &\bfseries Value &\bfseries Section\\ \hline
+\endhead
+ \hline \emph{Continued on next page}
+\endfoot
+ \hline
+\endlastfoot
+\DWSECTINFOTARG & 1 & \dotdebuginfodwo \\
+\textit(reserved) & 2 & \\
+\DWSECTABBREVTARG & 3 & \dotdebugabbrevdwo \\
+\DWSECTLINETARG & 4 & \dotdebuglinedwo \\
+\DWSECTLOCTARG & 5 & \dotdebuglocdwo \\
+\DWSECTSTROFFSETSTARG & 6 & \dotdebugstroffsetsdwo \\
+%DWSECTMACINFO & & \dotdebugmacinfodwo \\
+\DWSECTMACROTARG & 7 & \dotdebugmacrodwo \\
+\end{longtable}
+\end{centering}
+
+The offsets provided by the CU and TU index sections are the base
+offsets for the contributions made by each CU or TU to the
+corresponding section in the package file. Each CU and TU header
+contains an \texttt{abbrev\_offset} field, used to find the abbreviations
+table for that CU or TU within the contribution to the
+\dotdebugabbrevdwo{} section for that CU or TU, and should be
+interpreted as relative to the base offset given in the index
+section. Likewise, offsets into \dotdebuglinedwo{} from
+\DWATstmtlist{} attributes should be interpreted as relative to
+the base offset for \dotdebuglinedwo{}, and offsets into other debug
+sections obtained from DWARF attributes should also be
+interpreted as relative to the corresponding base offset.
+
+The table of sizes begins immediately following the table of
+offsets, and provides the sizes of the contributions made by each
+CU or TU to the corresponding section in the package file. Like
+the table of offsets, it is a two-dimensional array of 32-bit
+words, with L columns and N rows, in row-major order. Each row in
+the array is indexed starting from 1 (row 0 of the table of
+offsets also serves as the key for the table of sizes).
\needlines{6}
\section{32-Bit and 64-Bit DWARF Formats}
\addtoindex{initial length field}
(see
\addtoindexx{initial length field!encoding}
-Section \refersec{datarep:initiallengthvalues})
+Section \ref{datarep:initiallengthvalues} on page \pageref{datarep:initiallengthvalues})
is an unsigned 32\dash bit integer (which
must be less than \xfffffffzero); in the 64\dash bit DWARF format,
an \addtoindex{initial length field} is 96 bits in size,
\DWATmacros~\ddag &0x79&\livelink{chap:classmacptr}{macptr}
\addtoindexx{macro information attribute!encoding} \\
\DWATcallallcalls~\ddag &0x7a&\CLASSflag
- \addtoindexx{all calls summary attribute!encoding}\\
+ \addtoindexx{all calls summary attribute!encoding} \\
\DWATcallallsourcecalls~\ddag &0x7b &\CLASSflag
\addtoindexx{all source calls summary attribute!encoding} \\
\DWATcallalltailcalls~\ddag &0x7c&\CLASSflag
\addtoindexx{all tail calls summary attribute!encoding} \\
-\DWATcalldatalocation~\ddag &0x7d&\CLASSexprloc
+\DWATcalldatalocation~\ddag &0x7d &\CLASSexprloc
\addtoindexx{call data location attribute!encoding} \\
-\DWATcalldatavalue~\ddag &0x7e&\CLASSexprloc
+\DWATcalldatavalue~\ddag &0x7e &\CLASSexprloc
\addtoindexx{call data value attribute!encoding} \\
\DWATcallorigin~\ddag &0x7f &\CLASSexprloc
\addtoindexx{call origin attribute!encoding} \\
\DWLANGOCaml{} \ddag &0x001b &0 \addtoindexx{OCaml}\\
\DWLANGRust{} \ddag &0x001c &0 \addtoindexx{Rust}\\
\DWLANGCeleven{} \ddag &0x001d &0 \addtoindexx{C:2011 (ISO)}\\
+\DWLANGSwift{} \ddag &0x001e &0 \addtoindexx{Swift} \\
+\DWLANGJulia{} \ddag &0x001f &1 \addtoindexx{Julia} \\
\DWLANGlouser{} &0x8000 & \\
\DWLANGhiuser{} &\xffff & \\
that gives the actual length (see
Section \refersec{datarep:32bitand64bitdwarfformats}).
+\needlines{4}
\item \texttt{version} (\addtoindex{uhalf}) \\
A 2-byte version identifier containing the value
\versiondotdebugstroffsets{}
\addtoindexx{type unit}
type units.
+\needlines{4}
The type signature for a type T0 is formed from the
\MDfive{}\footnote{\livetarg{def:MDfive}{MD5} Message Digest Algorithm,
R.L. Rivest, RFC 1321, April 1992}
\DWFORMexprloc,
and \DWFORMblock.
+\needlines{4}
\item If the tag in Step 3 is one of \DWTAGpointertype,
\DWTAGreferencetype,
\DWTAGrvaluereferencetype,
encoding the type to allow for cases where a complete definition
of the type might not be available in all compilation units.}
+\needlines{4}
\textit{If a type definition contains the definition of a member function,
it cannot be moved as is into a type unit, because the member function
contains attributes that are unique to that compilation unit.
% 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}{May 27, 2014}
+\newcommand{\docdate}{June 18, 2014}
%
\usepackage{ifthen}
\newboolean{isdraft}
\include{introduction}
\include{generaldescription} %\emptypage
-\include{programscope} \emptypage
+\include{programscope} %\emptypage
\include{dataobject} \emptypage
\include{typeentries} %\emptypage
\include{otherdebugginginformation} %\emptypage
-\include{datarepresentation} %\emptypage
+\include{datarepresentation} \emptypage
% The \appendix toggles us into appendix chapters
\appendix
\include{encodingdecoding} \emptypage
\include{examples} %\emptypage
\include{compression} %\emptypage
-\include{splitobjects} %\emptypage
+\include{splitobjects} \emptypage
\include{sectionversionnumbers}
\include{gnulicense}
\newdwfnamecommands{DWLANGHaskell}{DW\_LANG\_Haskell}
\newdwfnamecommands{DWLANGhiuser}{DW\_LANG\_hi\_user}
\newdwfnamecommands{DWLANGJava}{DW\_LANG\_Java}
+\newdwfnamecommands{DWLANGJulia}{DW\_LANG\_Julia}
\newdwfnamecommands{DWLANGlouser}{DW\_LANG\_lo\_user}
\newdwfnamecommands{DWLANGModulatwo}{DW\_LANG\_Modula2}
\newdwfnamecommands{DWLANGModulathree}{DW\_LANG\_Modula3}
\newdwfnamecommands{DWLANGPLI}{DW\_LANG\_PLI}
\newdwfnamecommands{DWLANGPython}{DW\_LANG\_Python}
\newdwfnamecommands{DWLANGRust}{DW\_LANG\_Rust}
+\newdwfnamecommands{DWLANGSwift}{DW\_LANG\_Swift}
\newdwfnamecommands{DWLANGUPC}{DW\_LANG\_UPC}
\newdwfnamecommands{DWLANGCpluspluszerothree}{DW\_LANG\_C\_plus\_plus\_03}
\newdwfnamecommands{DWLANGCpluspluseleven}{DW\_LANG\_C\_plus\_plus\_11}
\newdwfnamecommands{DWORDcolmajor}{DW\_ORD\_col\_major}
\newdwfnamecommands{DWORDrowmajor}{DW\_ORD\_row\_major}
%
+% DW_SECT
+%
+\newdwfnamecommands{DWSECTABBREV}{DW\_SECT\_ABBREV}
+\newdwfnamecommands{DWSECTINFO}{DW\_SECT\_INFO}
+\newdwfnamecommands{DWSECTLINE}{DW\_SECT\_LINE}
+\newdwfnamecommands{DWSECTLOC}{DW\_SECT\_LOC}
+\newdwfnamecommands{DWSECTMACRO}{DW\_SECT\_MACRO}
+\newdwfnamecommands{DWSECTSTROFFSETS}{DW\_SECT\_STR\_OFFSETS}
+%
% DW_TAG
%
\newdwfnamecommands{DWTAGaccessdeclaration}{DW\_TAG\_access\_declaration}
\newcommand{\dotdebugstrdwo}{\addtoindex{\texttt{.debug\_str.dwo}}}
\newcommand{\dotdebugstroffsetsdwo}{\addtoindex{\texttt{.debug\_str\_offsets.dwo}}}
%
+\newcommand{\dotdebugcuindex}{\addtoindex{\texttt{.debug\_cu\_index}}}
+\newcommand{\dotdebugtuindex}{\addtoindex{\texttt{.debug\_tu\_index}}}
+%
\newcommand{\dotdata}{\addtoindex{\texttt{.data}}}
\newcommand{\dottext}{\addtoindex{\texttt{.text}}}
%
%
% DWARF Classes of Attribute Value
%
-\newcommand{\CLASSaddress} {\livelinki{chap:address}{address}{address class}}
-\newcommand{\CLASSaddrptr} {\livelinki{chap:addrptr}{addrptr}{addrptr class}}
-\newcommand{\CLASSblock} {\livelinki{chap:block}{block}{block class}}
-\newcommand{\CLASSconstant} {\livelinki{chap:constant}{constant}{constant class}}
-\newcommand{\CLASSexprloc} {\livelinki{chap:exprloc}{exprloc}{exprloc class}}
-\newcommand{\CLASSflag} {\livelinki{chap:flag}{flag}{flag class}}
-\newcommand{\CLASSlineptr} {\livelinki{chap:lineptr}{lineptr}{lineptr class}}
-\newcommand{\CLASSloclistptr} {\livelinki{chap:loclistptr}{loclistptr}{loclistptr class}}
-\newcommand{\CLASSmacptr} {\livelinki{chap:macptr}{macptr}{macptr class}}
-\newcommand{\CLASSrangelistptr} {\livelinki{chap:rangelistptr}{rangelistptr}{rangelistptr class}}
-\newcommand{\CLASSreference} {\livelinki{chap:reference}{reference}{reference class}}
-\newcommand{\CLASSstring} {\livelinki{chap:string}{string}{string class}}
-\newcommand{\CLASSstroffsetsptr}{\livelinki{chap:stroffsetsptr}{stroffsetsptr}{stroffsetsptr class}}
+\newcommand{\CLASSaddress} {\livelinki{chap:classaddress}{address}{address class}}
+\newcommand{\CLASSaddrptr} {\livelinki{chap:classaddrptr}{addrptr}{addrptr class}}
+\newcommand{\CLASSblock} {\livelinki{chap:classblock}{block}{block class}}
+\newcommand{\CLASSconstant} {\livelinki{chap:classconstant}{constant}{constant class}}
+\newcommand{\CLASSexprloc} {\livelinki{chap:classexprloc}{exprloc}{exprloc class}}
+\newcommand{\CLASSflag} {\livelinki{chap:classflag}{flag}{flag class}}
+\newcommand{\CLASSlineptr} {\livelinki{chap:classlineptr}{lineptr}{lineptr class}}
+\newcommand{\CLASSloclistptr} {\livelinki{chap:classloclistptr}{loclistptr}{loclistptr class}}
+\newcommand{\CLASSmacptr} {\livelinki{chap:classmacptr}{macptr}{macptr class}}
+\newcommand{\CLASSrangelistptr} {\livelinki{chap:classrangelistptr}{rangelistptr}{rangelistptr class}}
+\newcommand{\CLASSreference} {\livelinki{chap:classreference}{reference}{reference class}}
+\newcommand{\CLASSstring} {\livelinki{chap:classstring}{string}{string class}}
+\newcommand{\CLASSstroffsetsptr}{\livelinki{chap:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class}}
%
% Miscellaneous
%
\figurepart{1}{2}
\begin{dwflisting}
\begin{alltt}
-1\$: \DWTAGunspecifiedtype
- \DWATname("void")
- ...
+
2\$: \DWTAGbasetype
\DWATname("int")
...
3\$: \DWTAGclasstype
\DWATname("A")
...
-4\$: \DWTAGpointertype
+4\$: \DWTAGpointertype
\DWATtype(reference to 3\$)
...
-5\$: \DWTAGconsttype
+5\$: \DWTAGconsttype
\DWATtype(reference to 3\$)
...
-6\$: \DWTAGpointertype
+6\$: \DWTAGpointertype
\DWATtype(reference to 5\$)
...
-7\$: \DWTAGsubprogram
+7\$: \DWTAGsubprogram
\DWATdeclaration
\DWATname("func1")
- \DWATtype(reference to 1\$)
\DWATobjectpointer(reference to 8\$) \addtoindexx{object pointer attribute}
! References a formal parameter in this
! member function
...
+
\end{alltt}
\end{dwflisting}
\caption{Member function example: DWARF description}
\figurepart{2}{2}
\begin{dwflisting}
\begin{alltt}
-8\$: \DWTAGformalparameter
+
+8\$: \DWTAGformalparameter
\DWATartificial(true)
\DWATname("this")
\DWATtype(reference to 4\$)
! or volatile
\DWATlocation ...
...
-9\$: \DWTAGformalparameter
+9\$: \DWTAGformalparameter
\DWATname(x1)
\DWATtype(reference to 2\$)
...
10\$: \DWTAGsubprogram
- \DWATdeclaration
- \DWATname("func2")
- \DWATtype(reference to 1\$)
- \DWATobjectpointer(reference to 11\$) \addtoindexx{object pointer attribute}
- ! References a formal parameter in this
- ! member function
- ...
+ \DWATdeclaration
+ \DWATname("func2")
+ \DWATobjectpointer(reference to 11\$) \addtoindexx{object pointer attribute}
+ ! References a formal parameter in this
+ ! member function
+ ...
11\$: \DWTAGformalparameter
- \DWATartificial(true)
- \DWATname("this")
- \DWATtype(reference to 6\$)
- ! Makes type of 'this' as 'A const*' =>
- ! func2 marked as const
- \DWATlocation ...
- ...
+ \DWATartificial(true)
+ \DWATname("this")
+ \DWATtype(reference to 6\$)
+ ! Makes type of 'this' as 'A const*' =>
+ ! func2 marked as const
+ \DWATlocation ...
+ ...
12\$: \DWTAGsubprogram
- \DWATdeclaration
- \DWATname("func3")
- \DWATtype(reference to 1\$)
- ...
- ! No object pointer reference formal parameter
- ! implies func3 is static
+ \DWATdeclaration
+ \DWATname("func3")
+ ...
+ ! No object pointer reference formal parameter
+ ! implies func3 is static
13\$: \DWTAGformalparameter
- \DWATname(x3)
- \DWATtype(reference to 2\$)
- ...
+ \DWATname(x3)
+ \DWATtype(reference to 2\$)
+ ...
+
\end{alltt}
\end{dwflisting}
\begin{center}
\end{center}
\end{figure}
-As a further example illustrating \&- and \&\&-qualification,
+\clearpage
+As a further example illustrating \&- and \&\&-qualification
+of member functions,
consider the member function example fragment in
Figure \refersec{fig:memberfunctionrefqualexamplesourcefragment}.
The DWARF representation in
\label{fig:cimplicitpointerexample2dwarf}
\end{figure}
+\clearpage
+\section{String Type Examples}
+\label{app:stringtypeexamples}
+Consider the \addtoindex{Fortran 2003} string type example source in
+Figure \referfol{fig:stringtypeexamplesource}. The DWARF representation in
+Figure \refersec{fig:stringtypeexampledwarf} is appropriate.
+
+\begin{figure}[h]
+\begin{lstlisting}
+ program character_kind
+ use iso_fortran_env
+ implicit none
+ integer, parameter :: ascii = selected_char_kind ("ascii")
+ integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
+
+ character(kind=ascii, len=26) :: alphabet
+ character(kind=ucs4, len=30) :: hello_world
+ character (len=*), parameter :: all_digits="0123456789"
+
+ alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
+ hello_world = ucs4_'Hello World and Ni Hao -- ' &
+ // char (int (z'4F60'), ucs4) &
+ // char (int (z'597D'), ucs4)
+
+ write (*,*) alphabet
+ write (*,*) all_digits
+
+ open (output_unit, encoding='UTF-8')
+ write (*,*) trim (hello_world)
+ end program character_kind
+\end{lstlisting}
+\caption{String type example: source}
+\label{fig:stringtypeexamplesource}
+\end{figure}
+
+\begin{figure}[h]
+\begin{dwflisting}
+\begin{alltt}
+
+1\$: \DWTAGbasetype
+ \DWATencoding (\DWATEASCII)
+
+2\$: \DWTAGbasetype
+ \DWATencoding (\DWATEUCS)
+ \DWATbytesize (4)
+
+3\$: \DWTAGstringtype
+ \DWATbytesize (10)
+
+4\$: \DWTAGconsttype
+ \DWATtype (reference to 3\$)
+
+5\$: \DWTAGstringtype
+ \DWATtype (1\$)
+ \DWATstringlength ( ... )
+ \DWATstringlengthbytesize ( ... )
+ \DWATdatalocation ( ... )
+
+6\$: \DWTAGstringtype
+ \DWATtype (2\$)
+ \DWATstringlength ( ... )
+ \DWATstringlengthbytesize ( ... )
+ \DWATdatalocation ( ... )
+
+7\$: \DWTAGvariable
+ \DWATname (alphabet)
+ \DWATtype (5\$)
+ \DWATlocation ( ... )
+
+8\$: \DWTAGconstant
+ \DWATname (all\_digits)
+ \DWATtype (4\$)
+ \DWATconstvalue ( ... )
+
+9\$: \DWTAGvariable
+ \DWATname (hello\_world)
+ \DWATtype (6\$)
+ \DWATlocation ( ... )
+
+\end{alltt}
+\end{dwflisting}
+\caption{String type example: DWARF representation}
+\label{fig:stringtypeexampledwarf}
+\end{figure}
+
\clearpage
\section{Call Site Examples}
\label{app:callsiteexamples}
Possible generated code for this source is shown using a suggestive
pseudo-\linebreak[0]assembly notation in Figure \refersec{fig:callsiteexample2code}.
-\begin{figure}
+\begin{figure}[h]
\begin{lstlisting}
+
fn4:
%reg2 = [%reg0] ! Load value of n (passed by reference)
%reg2 = %reg2 / 2 ! Divide by 2
L10:
%reg3 = %reg3 + 8 ! Leave stack frame
return
+
\end{lstlisting}
\caption{Call Site Example \#2: Code}
\label{fig:callsiteexample2code}
The call sites in (just) function \texttt{fn5} might be as shown in
Figure \refersec{fig:callsiteexample2dwarf}.
-\begin{figure}
+\begin{figure}[h]
\begin{dwflisting}
\begin{alltt}
+
\DWTAGcallsite
\DWATcallreturnpc(L9) ! First call to fn4
\DWATcallorigin(reference to subprogram fn4)
! And the actual value of the parameter can be also perhaps looked up in
! fn5's caller
\DWATcalldatavalue(\DWOPentryvalue{} 4 \DWOPbregzero{} 0 \DWOPderefsize 4)
+
\DWTAGcallsite
\DWATcallreturnpc(L10) ! Second call to fn4
\DWATcallorigin(reference to subprogram fn4)
! DW_AT_call_data_location(DW_OP_push_object_address) ! left out, implicit
! And the value passed by reference is constant 5
\DWATcalldatavalue(\DWOPlitfive)
+
\end{alltt}
\end{dwflisting}
\caption{Call Site Example \#2: DWARF Encoding}
{Column position of inlined subroutine call}
{column position of inlined subroutine call} \\
\DWATcalldatalocationTARG{}
-&\livelinki{chap:DWATcalldatalocationofcallsite}
+&\livelinki{chap:DWATcalldatalocationofcallparameter}
{Address of the value pointed to by an argument passed in a call}
{address of the value pointed to by an argument passed in a call}
\index{call site!address of the value pointed to by an argument} \\
actual value of the object, rather than its location. The
\DWOPstackvalueNAME{} operation terminates the expression.
+\needlines{4}
\itembfnl{\DWOPimplicitpointerTARG}
The \DWOPimplicitpointerNAME{} operation specifies that the object
is a pointer that cannot be represented as a real pointer,
\DWATartificial{} attribute,
which is a \livelink{chap:classflag}{flag}.
+\needlines{6}
\section{Segmented Addresses}
\label{chap:segmentedaddresses}
\textit{In some systems, addresses are specified as offsets within a
\dotdebugranges{} section to the beginning of the
\addtoindex{range list}.
+\needlines{4}
If the current compilation unit contains a \DWATrangesbase{}
attribute, the value of that attribute establishes a base
offset within the \dotdebugranges{} section for the compilation
where the value may be known during compilation or may be
computed dynamically during execution.
+\needlines{5}
The value of these
attributes is determined based on the class as follows:
\begin{itemize}
the attribute.
\item For a \livelink{chap:classreference}{reference}, the
-value is a DWARF procedure that computes the value of the attribute.
+value is a reference to another DIE. This DIE may:
+\begin{itemize}
+\renewcommand{\itemsep}{0cm}
+\item describe a constant which is the attribute value,
+\item describe a variable which contains the attribute value, or
+\item contain a DWARF expression which computes the attribute value
+ (for example, be a \DWTAGdwarfprocedure{} entry).
+\end{itemize}
\item For an \livelink{chap:classexprloc}{exprloc}, the value is interpreted as a
DWARF expression;
should not accept them in expressions, nor allow them to be
assigned, or the like.}
+\needlines{4}
\section{Byte and Bit Sizes}
\label{chap:byteandbitsizes}
% Some trouble here with hbox full, so we try optional word breaks.
subroutine. If a consumer were to assume that it was in the
same context as the calling address, the unwind might fail.}
+\needlines{5}
\textit{For architectures with constant-length instructions where
the return address immediately follows the call instruction,
a simple solution is to subtract the length of an instruction
\DWLANGCpluspluselevenTARG & ISO C++:2011 \addtoindexx{C++:2011 (ISO)} \\
\DWLANGCobolseventyfourTARG & ISO COBOL:1974 \addtoindexx{COBOL:1974 (ISO)} \\
\DWLANGCoboleightyfiveTARG & ISO COBOL:1985 \addtoindexx{COBOL:1985 (ISO)} \\
-\DWLANGDTARG{} \dag & D \addtoindexx{D language} \\
+\DWLANGDTARG{}~\dag & D \addtoindexx{D language} \\
\DWLANGFortranseventysevenTARG & ISO FORTRAN:1977 \addtoindexx{FORTRAN:1977 (ISO)} \\
\DWLANGFortranninetyTARG & ISO Fortran:1990 \addtoindexx{Fortran:1990 (ISO)} \\
\DWLANGFortranninetyfiveTARG & ISO Fortran:1995 \addtoindexx{Fortran:1995 (ISO)} \\
-\DWLANGGoTARG{} \dag & \addtoindex{Go} \\
+\DWLANGGoTARG{}~\dag & \addtoindex{Go} \\
\DWLANGHaskellTARG{} \dag & \addtoindex{Haskell} \\
\DWLANGJavaTARG{} & \addtoindex{Java}\\
+\DWLANGJuliaTARG{}~\dag & \addtoindex{Julia} \\
\DWLANGModulatwoTARG & ISO Modula\dash 2:1996 \addtoindexx{Modula-2:1996 (ISO)} \\
\DWLANGModulathreeTARG & \addtoindex{Modula-3} \\
\DWLANGObjCTARG{} & \addtoindex{Objective C} \\
\DWLANGObjCplusplusTARG{} & \addtoindex{Objective C++} \\
-\DWLANGOCamlTARG{} \dag & \addtoindex{OCaml}\index{Objective Caml|see{OCaml}} \\
-\DWLANGOpenCLTARG{} \dag & \addtoindex{OpenCL} \\
+\DWLANGOCamlTARG{}~\dag & \addtoindex{OCaml}\index{Objective Caml|see{OCaml}} \\
+\DWLANGOpenCLTARG{}~\dag & \addtoindex{OpenCL} \\
\DWLANGPascaleightythreeTARG & ISO Pascal:1983 \addtoindexx{Pascal:1983 (ISO)} \\
-\DWLANGPLITARG{} \dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\
-\DWLANGPythonTARG{} \dag & \addtoindex{Python} \\
-\DWLANGRustTARG{} \dag & \addtoindex{Rust} \\
+\DWLANGPLITARG{}~\dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\
+\DWLANGPythonTARG{}~\dag & \addtoindex{Python} \\
+\DWLANGRustTARG{}~\dag & \addtoindex{Rust} \\
+\DWLANGSwiftTARG{}~\dag & \addtoindex{Swift} \\
\DWLANGUPCTARG{} & UPC (Unified Parallel C) \addtoindexx{UPC}
\index{Unified Parallel C|see{UPC}} \\
\hline
-\dag \ \ \textit{Support for these languages is limited.}& \\
+\dag \ \ \textit{Support for these languages is limited}& \\
\end{tabular}
\end{table}
unit entry, its children, and the skeleton line number table, are
represented using the UTF-8 representation.
+\needlines{4}
A \addtoindex{type unit} entry for a given type T owns a debugging
information entry that represents a defining declaration
of type T. If the type is nested within enclosing types or
with the tag
\DWTAGunspecifiedparametersTARG.
+\needlines{4}
The entry for a subroutine that includes a
\addtoindex{Fortran}
\addtoindexx{Fortran!common block}
subroutine and for which no concrete instance entry exists,
the reference should refer to the abstract instance entry.
+\needlines{4}
\item Entries in the concrete instance tree which are associated
with entries in the abstract instance tree such that neither
has a \DWATname{} attribute,
corresponding entries within the associated abstract instance
tree).
+\needlines{5}
The differences between the DWARF representation of a
concrete out\dash of\dash line instance of a given subroutine and the
representation of a concrete inlined instance of that same
The call site may have a
\DWATcalltargetNAME{}
-\livetargi{dwatcalltargetofcallsite}{attribute}{call target attribute} which is
+\livetargi{chap:DWATcalltargetofcallsite}{attribute}{call target attribute} which is
a DWARF expression. For indirect calls or jumps where it is unknown at
compile time which subprogram will be called the expression computes the
address of the subprogram that will be called. The DWARF expression should
The call site entry may have a
\DWATcalltargetclobberedNAME{}
-\livetargi{chap:DWATcalltargetclobbered}{attribute}{call target clobbered attribute}
+\livetargi{chap:DWATcalltargetclobberedofcallsite}{attribute}{call target clobbered attribute}
which is a DWARF expression. For indirect calls or jumps where the
address is not computable without use of registers or memory locations that
might be clobbered by the call the \DWATcalltargetclobberedNAME{}
locations that might be clobbered by the call, as it might be evaluated after
unwinding from the called function back to the caller.
+\needlines{4}
Each call site parameter entry may also have a
\DWATcallparameter{}
\livetargi{chap:DWATcallparameterofcallparameter}{attribute}{call parameter attribute}
\dotdebugabbrev{} & * & * & * & * \\
\dotdebugaddr{} & - & - & - & 5 \\
\dotdebugaranges{} & 2 & 2 & 2 & 2 \\
-\dotdebugframe{} & 1 & 3 & 4 & 4 \\
+\dotdebugframe{}\footnote{\textit{For the \dotdebugframe{} section, version 2 is unused.}}
+ & 1 & 3 & 4 & 4 \\
\dotdebuginfo{} & 2 & 3 & 4 & 5 \\
\dotdebugline{} & 2 & 3 & 4 & 5 \\
\dotdebugloc{} & * & * & * & 5 \\
\addtoindexi{\texttt{.debug\_types}}{\texttt{.debug\_types} (DWARF Version 4)}
& - & - & 4 & - \\
-\hspace{3cm}\textit{(.dwo sections)}\\
+\hspace{3.5cm}\textit{(.dwo sections)}\\
\dotdebugabbrevdwo & - & - & - & * \\
\dotdebuginfodwo & - & - & - & 5 \\
\dotdebuglinedwo & - & - & - & 5 \\
\dotdebugstrdwo & - & - & - & * \\
\dotdebugstroffsetsdwo
& - & - & - & 5 \\
+
+\hspace{3.5cm}\textit{(.dwp sections)}\\
+\dotdebugcuindex{} & - & - & - & 5 \\
+\dotdebugtuindex{} & - & - & - & 5 \\
+
\end{longtable}
\end{centering}
sections are the same.
\end{itemize}
-
-\textit{For the \dotdebugframe{} section, version 2 is unused.}
-
Higher numbers are reserved for future use.
All other attributes of the compilation unit DIE are moved to
the full DIE in the \dotdebuginfodwo{} section.
+\needlines{4}
Because of other improvements in \DWARFVersionV, most of the
relocations that would normally be found in the \dotdebuginfodwo{}
sections are moved to the \dotdebugaddr{} and
described below, these relocations are also eliminated.
\end{itemize}
+\needlines{4}
Each location list entry contains beginning and ending address
offsets, which normally may be relocated addresses. In the
\dotdebuglocdwo{} section, these offsets are replaced by indices
\section{Split DWARF Object Examples}
\label{app:splitdwarfobjectexamples}
-TBD
\ No newline at end of file
+[TBD]
+
+\section{DWARF Package File Example}
+\label{app:dwarfpackagefileexample}
+
+[TBD]
\end{tabular}
\end{table}
-The
-\DWATdigitcount{}
-attribute
-\addtoindexx{digit count attribute}
-is an \livelink{chap:classconstant}{integer constant}
-value that represents the number of digits in an instance of
-the type.
-
\hypertarget{chap:DWATdecimalscaledecimalscalefactor}{}
The \DWATdecimalscale{}
attribute
is larger than the digit count, this implies additional zero
digits on the left are not stored in an instance of the type.
+The
+\DWATdigitcount{}
+attribute
+\addtoindexx{digit count attribute}
+is an \livelink{chap:classconstant}{integer constant}
+value that represents the number of digits in an instance of
+the type.
+
The \DWATEedited{}
base
\hypertarget{chap:DWATpicturestringpicturestringfornumericstringtype}{}
\end{enumerate}
+\needlines{4}
For a \DWATdatabitoffset{} attribute,
the value is an \livelink{chap:classconstant}{integer constant}
(see Section \refersec{chap:staticanddynamicvaluesofattributes})
\label{fig:littleendiandatabitoffsets}
\end{figure}
+\needlines{4}
\textit{Note that data member bit offsets in this example are the
same for both big\dash\ and little\dash endian architectures even
though the fields are allocated in different directions
and arrays, see
Appendix \refersec{app:pascalexample}.}
+\needlines{4}
\textit{Attribute \DWATdatabitoffset{}
is new in
\addtoindex{DWARF Version 4}, unchanged in \addtoindex{DWARF Version 5},
is present, the size for holding an instance of the enumeration is given by the size
of the underlying data type.
+\needlines{4}
If an enumeration type has type safe
\addtoindexx{type safe enumeration types}
semantics such that
be described with a \doublequote{pointer to} modifier applied to a
user\dash defined type.}
+\needlines{4}
A subroutine type is represented by a debugging information
entry with the
\addtoindexx{subroutine type entry}
Section \refersec{chap:staticanddynamicvaluesofattributes}.
If the lower bound value is missing, the value is assumed to
-be a language\dash dependent default constant.
+be a language\dash dependent default constant as defined in
+Table \refersec{tab:languageencodings}.
\addtoindexx{lower bound attribute!default}
-The default lower bound is 0 for
-\addtoindex{C},
-\addtoindex{C++},
-\addtoindex{D},
-\addtoindex{Go},
-\addtoindex{Haskell},
-\addtoindex{Java},
-\addtoindex{Objective C},
-\addtoindex{Objective C++},
-\addtoindex{OpenCL},
-\addtoindex{Python},
-\addtoindex{Rust}, and
-\addtoindex{UPC}.
-The default lower bound is 1 for
-\addtoindex{Ada},
-\addtoindex{COBOL},
-\addtoindex{Fortran},
-\addtoindex{Modula-2},
-\addtoindex{Modula-3},
-\addtoindex{Pascal} and
-\addtoindex{PL/I}.
-
-\textit{No other default lower bound values are currently defined.}
If the upper bound and count are missing, then the upper bound value is
\textit{unknown}.\addtoindexx{upper bound attribute!default unknown}
\textit{Note that the stride can be negative.}
+\needlines{4}
\section{Pointer to Member Type Entries}
\label{chap:pointertomembertypeentries}
DWARF Git Projects / dwarf-doc.git / commitdiff