Posted a review document this date. Includes all issues and
authorRon Brender <ron.brender@gmail.com>
Wed, 18 Jun 2014 20:12:30 +0000 (16:12 -0400)
committerRon Brender <ron.brender@gmail.com>
Wed, 18 Jun 2014 20:12:30 +0000 (16:12 -0400)
review comments to date.

Signed-off-by: Ron Brender <ron.brender@gmail.com>
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/dwarfnamecmds.tex
dwarf5/latexdoc/examples.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/sectionversionnumbers.tex
dwarf5/latexdoc/splitobjects.tex
dwarf5/latexdoc/typeentries.tex

index 07af733..6f72960 100644 (file)
@@ -15,6 +15,12 @@ This change summary is included only in draft versions of this document.
 \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) \\
index 5a5d8d4..ea74431 100644 (file)
@@ -128,7 +128,7 @@ the other values is reserved for possible future extensions.
 
 
 
-\section{Relocatable, Split, Executable and Shared Objects} 
+\section{Relocatable, Split, Executable, Shared and Package Object Files} 
 \label{datarep:executableobjectsandsharedobjects}
 
 \subsection{Relocatable Objects}
@@ -237,6 +237,208 @@ shared object may be calculated by adding the offset to the
 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}
@@ -264,7 +466,7 @@ detailed in the following:
 \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,
@@ -1488,14 +1690,14 @@ Table \refersec{tab:attributeformencodings}.
 \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} \\
@@ -2132,6 +2334,8 @@ defined language.
 \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 & \\
 
@@ -2694,6 +2898,7 @@ DWARF format, this consists of the 4-byte value
 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{} 
@@ -2959,6 +3164,7 @@ the type definitions that are contained in
 \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}
@@ -3087,6 +3293,7 @@ to the following:
 \DWFORMexprloc,
 and \DWFORMblock.
 
+\needlines{4}
 \item If the tag in Step 3 is one of \DWTAGpointertype,
 \DWTAGreferencetype, 
 \DWTAGrvaluereferencetype,
@@ -3238,6 +3445,7 @@ information entry are encoded by name rather than by recursively
 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. 
index 4f83cfa..ecb421c 100644 (file)
@@ -3,7 +3,7 @@
 % 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}
@@ -312,11 +312,11 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 
 \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
@@ -326,7 +326,7 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \include{encodingdecoding}              \emptypage
 \include{examples}                      %\emptypage
 \include{compression}                   %\emptypage
-\include{splitobjects}                 %\emptypage
+\include{splitobjects}                 \emptypage
 \include{sectionversionnumbers}
 \include{gnulicense}
 
index 4e6efb1..b273634 100644 (file)
 \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
 %
index c38c7fc..ec15850 100644 (file)
@@ -1333,33 +1333,31 @@ void A::func1(int x) {}
 \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}
@@ -1370,7 +1368,8 @@ void A::func1(int x) {}
 \figurepart{2}{2}
 \begin{dwflisting}
 \begin{alltt}
-8\$:        \DWTAGformalparameter
+
+8\$:         \DWTAGformalparameter
                 \DWATartificial(true)
                 \DWATname("this")
                 \DWATtype(reference to 4\$)
@@ -1379,37 +1378,36 @@ void A::func1(int x) {}
                     ! 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}
@@ -1417,7 +1415,9 @@ Figure~\ref{fig:memberfunctionexampledwarfdescription}: Member function example:
 \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 
@@ -2967,6 +2967,91 @@ int main ()
 \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}
@@ -3241,8 +3326,9 @@ end subroutine fn5
 
 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
@@ -3262,6 +3348,7 @@ L9:
 L10:
     %reg3 = %reg3 + 8 ! Leave stack frame
     return
+    
 \end{lstlisting}
 \caption{Call Site Example \#2: Code}
 \label{fig:callsiteexample2code}
@@ -3276,9 +3363,10 @@ DW_OP_entry_value 4 DW_OP_breg0 0 DW_OP_deref_size 4 DW_OP_stack_value
 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)
@@ -3292,6 +3380,7 @@ Figure \refersec{fig:callsiteexample2dwarf}.
         ! 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)
@@ -3304,6 +3393,7 @@ Figure \refersec{fig:callsiteexample2dwarf}.
         ! 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}
index db95c6b..1c4fa27 100644 (file)
@@ -218,7 +218,7 @@ The attributes are listed in Table \referfol{tab:attributenames}.
            {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} \\
@@ -1513,6 +1513,7 @@ of location description, the DWARF expression represents the
 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,
@@ -2073,6 +2074,7 @@ may have a
 \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
@@ -2487,6 +2489,7 @@ value is represented as an offset from the beginning of the
 \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
@@ -2620,6 +2623,7 @@ as the lower bound of an array) that is an integer value,
 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}
@@ -2627,7 +2631,14 @@ attributes is determined based on the class as follows:
 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; 
@@ -2685,6 +2696,7 @@ descriptions as part of the description of other entities. It
 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.
index de0a54c..c7df5be 100644 (file)
@@ -2154,6 +2154,7 @@ or past the end of the calling
 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
index 9b3f332..0f47422 100644 (file)
@@ -152,27 +152,29 @@ Language name & Meaning\\ \hline
 \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}
 
@@ -545,6 +547,7 @@ whose presence indicates that all strings referred to by this type
 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
@@ -1257,6 +1260,7 @@ represented by a debugging information entry\addtoindexx{unspecified parameters
 with the tag
 \DWTAGunspecifiedparametersTARG.
 
+\needlines{4}
 The entry for a subroutine that includes a
 \addtoindex{Fortran}
 \addtoindexx{Fortran!common block}
@@ -1743,6 +1747,7 @@ to an entity declared within the scope of the relevant inlined
 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,
@@ -1803,6 +1808,7 @@ a concrete inlined instance (that is, as references to
 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
@@ -2045,7 +2051,7 @@ the subroutine pointer that is called.
 
 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
@@ -2053,7 +2059,7 @@ not use register or memory locations that might be clobbered by the call.
 
 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{}
@@ -2121,6 +2127,7 @@ The expression should not use registers or memory
 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}
index 28d7993..cb5ed7c 100644 (file)
@@ -41,7 +41,8 @@ format would be represented by a change in the
 \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 \\
@@ -55,7 +56,7 @@ format would be represented by a change in the
 \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 \\
@@ -64,6 +65,11 @@ format would be represented by a change in the
 \dotdebugstrdwo     & - & - & - & * \\
 \dotdebugstroffsetsdwo 
                     & - & - & - & 5 \\
+                    
+\hspace{3.5cm}\textit{(.dwp sections)}\\
+\dotdebugcuindex{}  & - & - & - & 5 \\
+\dotdebugtuindex{}  & - & - & - & 5 \\
+
 \end{longtable}
 \end{centering}
 
@@ -85,8 +91,5 @@ version of the DWARF standard.
 sections are the same.
 
 \end{itemize}
-
-\textit{For the \dotdebugframe{} section, version 2 is unused.}
-
 Higher numbers are reserved for future use.
 
index 68d37b9..31fe10b 100644 (file)
@@ -155,6 +155,7 @@ not used, and vice versa.
 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
@@ -206,6 +207,7 @@ With a minor change to the location list entry format,
 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
@@ -271,4 +273,9 @@ used to locate the line number tables.
 \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]
index b2d5853..abbbd40 100644 (file)
@@ -230,14 +230,6 @@ indicating positive or negative. \\
 \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 
@@ -253,6 +245,14 @@ decimal point to the left; if the absolute value of the scale
 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}{}
@@ -1185,6 +1185,7 @@ do not allow for manipulating or computing bit offsets.}
 
 \end{enumerate}
 
+\needlines{4}
 For a \DWATdatabitoffset{} attribute, 
 the value is an \livelink{chap:classconstant}{integer constant} 
 (see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
@@ -1309,6 +1310,7 @@ the right.}
 \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
@@ -1320,6 +1322,7 @@ the target architecture may or may not make this seem natural.}
 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},
@@ -1683,6 +1686,7 @@ required to hold an instance of the enumeration. If no \DWATbytesize{} attribute
 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
@@ -1770,6 +1774,7 @@ arguments of specific types. The type of such pointers would
 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}
@@ -2052,31 +2057,9 @@ these attributes is determined as described in
 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}
@@ -2115,6 +2098,7 @@ Section \refersec{chap:byteandbitsizes}.
 
 \textit{Note that the stride can be negative.}
 
+\needlines{4}
 \section{Pointer to Member Type Entries}
 \label{chap:pointertomembertypeentries}