Update for the November 22, 2013 version of the document.
authorRon Brender <ron.brender@gmail.com>
Sat, 23 Nov 2013 20:12:23 +0000 (15:12 -0500)
committerRon Brender <ron.brender@gmail.com>
Sat, 23 Nov 2013 20:12:23 +0000 (15:12 -0500)
Included are all approved issues and review comments up to
that date.

Signed-off-by: Ron Brender <ron.brender@gmail.com>
dwarf5/latexdoc/attributesbytag.tex
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/debugsectionrelationships.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/dwarfnamecmds.tex
dwarf5/latexdoc/examples.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/splitobjects.tex [new file with mode: 0644]
dwarf5/latexdoc/typeentries.tex

index 1d3b5d3..0bb77f1 100644 (file)
@@ -149,6 +149,8 @@ means include all three of the
 &\DWATaddrbase{} \\
 &\DWATbasetypes{} \\
 &\DWATcompdir{} \\
+&\DWATdwoid{} \\
+&\DWATdwoname{} \\
 &\DWATentrypc{} \\
 &\DWATidentifiercase{} \\
 &\DWAThighpc{} \\
@@ -161,8 +163,8 @@ means include all three of the
 &\DWATranges{} \\
 &\DWATrangesbase{} \\
 &\DWATsegment{} \\
-&\DWATstmtlist{} \\
-&\DWATstroffsetsbase{} \\
+&\DWATstmtlist{} \\*
+&\DWATstroffsetsbase{} \\*
 &\DWATuseUTFeight{} \\
 
 \hline
@@ -200,6 +202,18 @@ means include all three of the
 \DWTAGdwarfprocedure
 &\DWATlocation{} \\
 
+\hline
+\DWTAGdynamictype
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin \\*
+&\DWATallocated \\*
+&\DWATassociated \\
+&\DWATdatalocation \\
+&\DWATdescription \\
+&\DWATname \\
+&\DWATtype \\
+&\DWATsibling \\
+
 \hline
 \DWTAGentrypoint
 &\livelink{chap:DECL}{DECL} \\
@@ -248,9 +262,9 @@ means include all three of the
 
 \hline
 \DWTAGfiletype
-&\livelink{chap:DECL}{DECL} \\
-&\DWATabstractorigin{} \\
-&\DWATallocated{} \\
+&\livelink{chap:DECL}{DECL} \\*
+&\DWATabstractorigin{} \\*
+&\DWATallocated{} \\*
 &\DWATassociated{} \\
 &\DWATbitsize{} \\
 &\DWATbytesize{} \\
@@ -289,9 +303,9 @@ means include all three of the
 \hline
 % Please keep in synch with DW_TAG_subrange_type.
 \DWTAGgenericsubrange
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATabstractorigin{}  \\
-&\DWATaccessibility{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATabstractorigin{}  \\*
+&\DWATaccessibility{}  \\*
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATbitsize{}  \\
@@ -316,9 +330,9 @@ means include all three of the
 &\DWATaccessibility{} \\
 &\DWATdescription{} \\
 &\DWATimport{} \\
-&\DWATname{} \\
-&\DWATsibling{} \\
-&\DWATstartscope{} \\
+&\DWATname{} \\*
+&\DWATsibling{} \\*
+&\DWATstartscope{} \\*
 
 \hline
 \DWTAGimportedmodule
@@ -362,9 +376,9 @@ means include all three of the
 &\livelink{chap:DECL}{DECL} \\
 &\DWATaccessibility{} \\
 &\DWATdescription{} \\
-&\DWATname{} \\
-&\DWATsibling{} \\
-&\DWATstartscope{} \\
+&\DWATname{} \\*
+&\DWATsibling{} \\*
+&\DWATstartscope{} \\*
 
 \hline
 \DWTAGlabel
@@ -446,9 +460,9 @@ means include all three of the
 &\livelink{chap:DECL}{DECL} \\
 &\DWATdescription{} \\
 &\DWATextension{} \\
-&\DWATname{} \\
-&\DWATsibling{} \\
-&\DWATstartscope{} \\
+&\DWATname{} \\*
+&\DWATsibling{} \\*
+&\DWATstartscope{} \\*
 
 \hline
 \DWTAGpackedtype
@@ -461,8 +475,8 @@ means include all three of the
 
 \hline
 \DWTAGpartialunit
-&\DWATaddrbase{} \\
-&\DWATbasetypes{}  \\  
+&\DWATaddrbase{} \\*
+&\DWATbasetypes{}  \\*  
 &\DWATcompdir{}  \\
 &\DWATdescription{}  \\
 &\DWATentrypc{} \\
@@ -530,8 +544,8 @@ means include all three of the
 
 \hline
 \DWTAGrvaluereferencetype
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATaddressclass{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATaddressclass{}  \\*
 &\DWATallocated{}  \\
 &\DWATassociated{}  \\
 &\DWATdatalocation{}  \\
@@ -608,8 +622,8 @@ means include all three of the
 
 \hline
 \DWTAGsubprogram
-&\livelink{chap:DECL}{DECL}  \\
-&\DWATabstractorigin{}  \\
+&\livelink{chap:DECL}{DECL}  \\*
+&\DWATabstractorigin{}  \\*
 &\DWATaccessibility{}  \\
 &\DWATaddressclass{}  \\
 &\DWATartificial{}  \\
@@ -717,9 +731,9 @@ means include all three of the
 &\DWATconstvalue{}   \\
 &\DWATdefaultvalue{}   \\
 &\DWATdescription{}   \\
-&\DWATname{}   \\
-&\DWATsibling{}   \\
-&\DWATtype{}   \\
+&\DWATname{}   \\*
+&\DWATsibling{}   \\*
+&\DWATtype{}   \\*
 
 \hline
 \DWTAGthrowntype
@@ -759,9 +773,9 @@ means include all three of the
 
 \hline
 \DWTAGtypeunit
-&\DWATaddrbase{} \\
-&\DWATlanguage{} \\
-&\DWATstroffsetsbase{} \\
+&\DWATaddrbase{} \\*
+&\DWATlanguage{} \\*
+&\DWATstroffsetsbase{} \\*
 
 \hline
 \DWTAGuniontype
@@ -842,9 +856,9 @@ means include all three of the
 &\DWATallocated{}   \\
 &\DWATassociated{}    \\
 &\DWATdatalocation{}    \\
-&\DWATname{}    \\
-&\DWATsibling{}    \\
-&\DWATtype{}    \\
+&\DWATname{}    \\*
+&\DWATsibling{}    \\*
+&\DWATtype{}    \\*
 
 \hline
 \DWTAGwithstmt
index 05a94c6..3280f4e 100644 (file)
@@ -14,6 +14,7 @@ This change summary is included only in draft versions of this document.
 \vspace{1cm}
 \begin{tabular}{ll}
 \textbf{Date}  & \textbf{Issue Incorported or Other Change}    \\ \hline       \\
+11/22/2013      & 131106.1 (dynamic type), review comments to date \\
 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),   \\
index 10c4733..83294ed 100644 (file)
@@ -126,29 +126,11 @@ the other values is reserved for possible future extensions.
 
 
 
-\section{Relocatable, Executable, Shared and Split Objects} 
+\section{Relocatable, Split, Executable and Shared Objects} 
 \label{datarep:executableobjectsandsharedobjects}
 
 \subsection{Relocatable Objects}
 
-\subsection{Executable Objects}
-\label{chap:executableobjects}
-The relocated addresses in the debugging information for an
-executable object are virtual addresses.
-
-\subsection{Shared Objects}
-\label{datarep:sharedobjects}
-The relocated
-addresses in the debugging information for a shared object
-are offsets relative to the start of the lowest region of
-memory loaded from that shared object.
-
-\textit{This requirement makes the debugging information for
-shared objects position independent.  Virtual addresses in a
-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{Split DWARF Objects}
 \label{datarep:splitdwarfobjects}
 A DWARF producer may partition the debugging
@@ -234,6 +216,24 @@ to a debugging information section (for example, \dotdebuginfo),
 applies also to the corresponding split DWARF section (for example,
 \dotdebuginfodwo).
 
+\subsection{Executable Objects}
+\label{chap:executableobjects}
+The relocated addresses in the debugging information for an
+executable object are virtual addresses.
+
+\subsection{Shared Objects}
+\label{datarep:sharedobjects}
+The relocated
+addresses in the debugging information for a shared object
+are offsets relative to the start of the lowest region of
+memory loaded from that shared object.
+
+\textit{This requirement makes the debugging information for
+shared objects position independent.  Virtual addresses in a
+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.}
+
 
 \section{32-Bit and 64-Bit DWARF Formats}
 \label{datarep:32bitand64bitdwarfformats}
@@ -346,6 +346,17 @@ section) depends on the DWARF format as follows: in the
 32\dash bit DWARF format, this field is a 32\dash bit unsigned integer;
 in the 64\dash bit DWARF format, it is a 64\dash bit unsigned integer.
 
+\needlines{4}
+\item In the body of the \dotdebugstroffsets{} and \dotdebugstroffsetsdwo{}
+sections, the size of entries in the body depend on the DWARF
+format as follows: in the 32-bit DWARF format, entries are 32-bit
+unsigned integer values; in the 64-bit DWARF format, they are
+64-bit unsigned integers.
+
+\item In the body of the \dotdebugaddr{}, \dotdebugloc{} and \dotdebugranges{}
+sections, the contents of the address size fields depends on the
+DWARF format as follows: in the 32-bit DWARF format, these fields
+contain 4; in the 64-bit DWARF format these fields contain 8.
 \end{enumerate}
 
 
@@ -602,7 +613,7 @@ Table \refersec{tab:tagencodings}.
 \endhead
   \hline \emph{Continued on next page}
 \endfoot
-  \hline
+  \hline \ddag\ \textit{New in DWARF Version 5}
 \endlastfoot
 \DWTAGarraytype{} &0x01 \\
 \DWTAGclasstype&0x02 \\
@@ -664,8 +675,9 @@ Table \refersec{tab:tagencodings}.
 \DWTAGtypeunit{} &0x41      \\
 \DWTAGrvaluereferencetype{} &0x42      \\
 \DWTAGtemplatealias{} &0x43      \\
-\DWTAGcoarraytype &0x44 \\
-\DWTAGgenericsubrange &0x45 \\
+\DWTAGcoarraytype~\ddag &0x44 \\
+\DWTAGgenericsubrange~\ddag &0x45 \\
+\DWTAGdynamictype~\ddag & 0x46 \\
 \DWTAGlouser&0x4080      \\
 \DWTAGhiuser&\xffff      \\
 \end{longtable}
@@ -791,6 +803,7 @@ The new
 \DWFORMsecoffset{} replaces
 their usage for the other classes.}
 
+\needlines{4}
 Each possible form belongs to one or more of the following classes:
 
 \begin{itemize}
@@ -806,7 +819,7 @@ The size is encoded in the compilation unit header
 This address is relocatable in a relocatable object file and
 is relocated in an executable file or shared object.
 
-\item As an indirect index into a table of addresses (as 
+\item An indirect index into a table of addresses (as 
 described in the previous bullet) in the
 \dotdebugaddr{} section (\DWFORMaddrxTARG). 
 The representation of a \DWFORMaddrxNAME{} value is an unsigned
@@ -859,6 +872,7 @@ signed (\DWFORMsdataTARG) and unsigned
 (\DWFORMudataTARG) variable
 length constants are available
 
+\needlines{4}
 The data in \DWFORMdataone, 
 \DWFORMdatatwo, 
 \DWFORMdatafour{} and
@@ -1357,7 +1371,7 @@ Table \refersec{tab:attributeformencodings}.
 \end{longtable} 
 \end{centering}
 
-
+\needlines{8}
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|l|l}
@@ -1655,6 +1669,8 @@ a base address selection entry, or an
 \addtoindexx{end of list entry!in location list}
 end of list entry.
 
+\needlines{6}
+\subsubsection{Location List Entries in Non-Split Objects}
 A \addtoindex{location list} entry consists of two address offsets followed
 by a 2\dash byte length, followed by a block of contiguous bytes
 that contains a DWARF location description. The length
@@ -1673,6 +1689,32 @@ For a \addtoindex{location list} to be specified, the base address of
 the corresponding compilation unit must be defined 
 (see Section  \refersec{chap:normalandpartialcompilationunitentries}).
 
+\subsubsection{Location List Entries in Split Objects}
+An alternate form for location list entries is used in split objects. 
+Each entry begins with a one-byte code that indicates the kind of entry
+that follows. The encodings for these constants are given in
+Table \refersec{tab:locationlistentryencodingvalues}.
+
+\begin{centering}
+\setlength{\extrarowheight}{0.1cm}
+\begin{longtable}{l|c}
+  \caption{Location list entry encoding values} \label{tab:locationlistentryencodingvalues} \\
+  \hline \bfseries Location list entry encoding name&\bfseries Value \\ \hline
+\endfirsthead
+  \bfseries Location list entry encoding name&\bfseries Value\\ \hline
+\endhead
+  \hline \emph{Continued on next page}
+\endfoot
+  \hline
+\endlastfoot
+\DWLLEendoflistentry & 0x0 \\
+\DWLLEbaseaddressselectionentry & 0x01 \\
+\DWLLEstartendentry & 0x02 \\
+\DWLLEstartlengthentry & 0x03 \\
+\DWLLEoffsetpairentry & 0x04 \\
+\end{longtable}
+\end{centering}
+
 \section{Base Type Attribute Encodings}
 \label{datarep:basetypeattributeencodings}
 
index a1c7794..4b09626 100644 (file)
@@ -74,7 +74,7 @@ versus \dotdebuginfodwo).}
 %
 \node(zsectabb)        at (12, 16) [sect] {\dotdebugabbrev};
 \node(zsectstr)        at (12, 14) [sect] {\dotdebugstr};
-\node(zlinkl)   at (12, 12) [link] {To strings (k)};
+\node(zlinkl)   at (12, 12) [link] {To strings (l)};
 \node(zsectstx) at (12, 10) [sect] {\dotdebugstroffsets};
 \node(zsectloc)        at (12,  8) [sect] {\dotdebugloc};
 \node(zsectran)        at (12,  6) [sect] {\dotdebugranges};
@@ -204,7 +204,7 @@ indices relative to the beginning of that section.
 %l
 \item \dotdebugstroffsets{} to \dotdebugstr \\
 Entries in the string offsets table
-are offsets to the corresponding string in the 
+are offsets to the corresponding string text in the 
 \dotdebugstr{} section.
 
 \end{enumerate}
index 71adcd2..5ca596b 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}{October 27, 2013}
+\newcommand{\docdate}{November 22, 2013}
 %
 \usepackage{ifthen}
 \newboolean{isdraft}
@@ -311,14 +311,14 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \include{generaldescription}            \emptypage
 \include{programscope}                  \emptypage
 \include{dataobject}                    \emptypage
-\include{typeentries}                   %\emptypage
+\include{typeentries}                   \emptypage
 \include{otherdebugginginformation}    \emptypage
-\include{datarepresentation}            \emptypage
+\include{datarepresentation}            %\emptypage
 
 %  The \appendix toggles us into appendix chapters
 \appendix
 
-\include{attributesbytag}                              \emptypage
+\include{attributesbytag}                              %\emptypage
 \include{debugsectionrelationships}     %\emptypage
 \include{encodingdecoding}              \emptypage
 \include{examples}                      %\emptypage
index 4b44ff8..44ddf6e 100644 (file)
 \newdwfnamecommands{DWTAGconstant}{DW\_TAG\_constant}
 \newdwfnamecommands{DWTAGdescriptortype}{DW\_TAG\_descriptor\_type}
 \newdwfnamecommands{DWTAGdwarfprocedure}{DW\_TAG\_dwarf\_procedure}
+\newdwfnamecommands{DWTAGdynamictype}{DW\_TAG\_dynamic\_type}
 \newdwfnamecommands{DWTAGentrypoint}{DW\_TAG\_entry\_point}
 \newdwfnamecommands{DWTAGenumerationtype}{DW\_TAG\_enumeration\_type}
 \newdwfnamecommands{DWTAGenumerator}{DW\_TAG\_enumerator}
index 95e53fe..04fbb7f 100644 (file)
@@ -215,7 +215,7 @@ The following examples illustrate how to represent some of
 the more complicated forms of array and record aggregates
 using DWARF.
 
-\subsection{Fortran Array Example}
+\subsection{Fortran Simple Array Example}
 \label{app:fortranarrayexample}
 Consider the \addtoindex{Fortran array}\addtoindexx{Fortran 90} source fragment in 
 \addtoindexx{array type entry!examples}
@@ -999,7 +999,7 @@ little\dash endian
 architectures using the conventions described in 
 Section \refersec{chap:datamemberentries}.
 
-\begin{figure}[p]
+\begin{figure}[h]
 \figurepart{1}{2}
 \begin{dwflisting}
 \begin{alltt}
@@ -1017,6 +1017,16 @@ Section \refersec{chap:datamemberentries}.
             \DWATtype(reference to 10$)
             \DWATdatabitoffset(0)        ! may be omitted
             \DWATbitsize(1)
+\end{alltt}
+\end{dwflisting}
+\caption{Packed record example: DWARF description}
+\label{fig:packedrecordexampledwarfdescription}
+\end{figure}
+
+\begin{figure}[h]
+\figurepart{2}{2}
+\begin{dwflisting}
+\begin{alltt}
         \DWTAGmember
             \DWATname("F6")
             \DWATtype(reference to 10$)
@@ -1051,16 +1061,6 @@ Section \refersec{chap:datamemberentries}.
             \DWATtype(reference to 22\$)
             \DWATdatabitoffset(33)
             \DWATbitsize(4) ! may be omitted
-\end{alltt}
-\end{dwflisting}
-\caption{Packed record example: DWARF description}
-\label{fig:packedrecordexampledwarfdescription}
-\end{figure}
-
-\begin{figure}[p]
-\figurepart{2}{2}
-\begin{dwflisting}
-\begin{alltt}
         \DWTAGmember
             \DWATname("F7")
             \DWATtype(reference to 20\$)    ! type T
@@ -1078,6 +1078,87 @@ Figure~\ref{fig:packedrecordexampledwarfdescription}: Packed record example: DWA
 \end{center}
 \end{figure}
 
+\clearpage
+\subsection{Fortran Dynamic Type Example}
+\label{app:fortrandynamictypeexample}
+Consider the \addtoindex{Fortran 90} example of dynamic properties in 
+Figure \refersec{fig:fortrandynamictypeexamplesource}.
+This can be represented in DWARF as illustrated in 
+Figure \refersec{fig:fortrandynamictypeexampledwarfdescription}.
+Note that unnamed dynamic types are used to avoid replicating
+the full description of the underlying type \texttt{dt} that is shared by
+several variables.
+
+\begin{figure}[h]
+\begin{lstlisting}
+           program sample
+     
+        type :: dt (l)
+            integer, len :: l
+            integer :: arr(l)
+        end type
+
+        integer :: n = 4
+        contains
+
+        subroutine s()
+            type (dt(n))               :: t1
+            type (dt(n)), pointer      :: t2
+            type (dt(n)), allocatable  :: t3, t4
+        end subroutine
+     
+        end sample
+\end{lstlisting}
+\caption{Fortran dynamic type example: source}
+\label{fig:fortrandynamictypeexamplesource}
+\end{figure}
+
+\begin{figure}[h]
+\begin{dwflisting}
+\begin{alltt}
+11$:    \DWTAGstructuretype
+            \DWATname("dt")
+            \DWTAGmember
+                ...
+                       ...
+
+13$:    \DWTAGdynamictype             ! plain version
+            \DWATdatalocation (dwarf expression to locate raw data)
+            \DWATtype (11$)
+
+14$:    \DWTAGdynamictype             ! 'pointer' version
+            \DWATdatalocation (dwarf expression to locate raw data)
+            \DWATassociated (dwarf expression to test if associated)
+            \DWATtype (11$)
+
+15$:    \DWTAGdynamictype             ! 'allocatable' version
+            \DWATdatalocation (dwarf expression to locate raw data)
+            \DWATallocated (dwarf expression to test is allocated)
+            \DWATtype (11$)
+
+16$:    \DWTAGvariable
+            \DWATname ("t1")
+            \DWATtype (13$)
+            \DWATlocation (dwarf expression to locate descriptor)
+17$:    \DWTAGvariable
+            \DWATname ("t2")
+            \DWATtype (14$)
+            \DWATlocation (dwarf expression to locate descriptor)
+18$:    \DWTAGvariable
+            \DWATname ("t3")
+            \DWATtype (15$)
+            \DWATlocation (dwarf expression to locate descriptor)
+19$:    \DWTAGvariable
+            \DWATname ("t4")
+            \DWATtype (15$)
+            \DWATlocation (dwarf expression to locate descriptor)
+\end{alltt}
+\end{dwflisting}
+\caption{Fortran dynamic type example: DWARF description}
+\label{fig:fortrandynamictypeexampledwarfdescription}
+\end{figure}
+
+\clearpage
 \section{Namespace Example}
 \label{app:namespaceexample}
 
@@ -1090,7 +1171,7 @@ The DWARF representation in
 Figure \refersec{fig:namespaceexampledwarfdescription}
 is appropriate.
 
-\begin{figure}[p]
+\begin{figure}[h]
 \begin{lstlisting}
 namespace {
     int i;
@@ -1224,6 +1305,7 @@ Figure~\ref{fig:namespaceexampledwarfdescription}: Namespace example: DWARF desc
 \end{center}
 \end{figure}
 
+\clearpage
 \section{Member Function Example}
 \label{app:memberfunctionexample}
 
@@ -1233,7 +1315,7 @@ The DWARF representation in
 Figure \refersec{fig:memberfunctionexampledwarfdescription}
 is appropriate.
 
-\begin{figure}[Here]
+\begin{figure}[h]
 \begin{lstlisting}
 class A
 {
@@ -1452,7 +1534,7 @@ SPECIAL(1, 0) && 0xa        \\
 \end{longtable}
 \end{centering}
 
-
+\needlines{6}
 \section{Call Frame Information Example}
 \label{app:callframeinformationexample}
 
index 76dc3ce..c99a28e 100644 (file)
@@ -44,6 +44,7 @@ described in Chapters 3, 4 and 5.
 \DWTAGconsttype,
 \DWTAGconstant,
 \DWTAGdwarfprocedure,
+\DWTAGdynamictype,
 \DWTAGentrypoint,
 \DWTAGenumerationtype,
 \DWTAGenumerator,
@@ -2577,7 +2578,12 @@ A type or value parameter entry may have a \DWATname{} attribute,
 \addtoindexx{name attribute}
 whose value is a
 null\dash terminated string containing the name of the corresponding 
-formal parameter as it appears in the source program. 
+formal parameter as it appears in the source program.
+The entry may also have a 
+\DWATdefaultvalue{} attribute, which is a flag indicating 
+that the value corresponds to the default argument for the 
+template parameter.
+
 
 A
 \addtoindexx{formal type parameter|see{template type parameter entry}}
@@ -2586,16 +2592,15 @@ template type parameter entry has a
 \DWATtype{} attribute
 describing the actual type by which the formal is replaced.
 
-A value parameter entry has an attribute giving the 
+
+A template value parameter entry has a \DWATtype{} attribute 
+describing the type of the parameterized value.
+The entry also has an attribute giving the 
 actual compile-time or run-time constant value 
 of the value parameter for this instantiation.
 This can be a \DWATconstvalue{} attribute, whose
 value is the compile-time constant value as represented 
 on the target architecture. 
-Or, it can a \DWATlocation{} attribute, whose value is a 
+Or, the attribute can be a \DWATlocation{} attribute, whose value is a 
 single location description for the run-time constant address.
-The entry may also have a 
-\DWATdefaultvalue{} attribute, which is a flag indicating 
-that the value corresponds to the default argument for the 
-template parameter.
 
index 8f9307c..1c1e2c9 100644 (file)
@@ -412,9 +412,15 @@ Section \refersec{datarep:typesignaturecomputation}.
 A \DWATrangesbase{} attribute (the same as for regular
 compilation unit entries).
 
+\needlines{6}
 \item
 A \DWATaddrbase{} attribute (the same as for regular
 compilation unit entries).
+
+\item
+A \DWATstroffsetsbase{} attribute, for indirect strings references 
+from the skeleton compilation unit (the same as for regular 
+compilation unit entries).
 \end{enumerate}
 
 All other attributes of a compilation unit entry (described
@@ -1309,7 +1315,7 @@ With the following
 exceptions, such an entry will contain the same attributes and
 will have the same types of child entries as would an entry
 for a subroutine defined explicitly using the instantiation
-types. The exceptions are:
+types and values. The exceptions are:
 
 \begin{enumerate}[1. ]
 \item Template parameters are described and referenced as specified in
diff --git a/dwarf5/latexdoc/splitobjects.tex b/dwarf5/latexdoc/splitobjects.tex
new file mode 100644 (file)
index 0000000..ae4e719
--- /dev/null
@@ -0,0 +1,275 @@
+\chapter[Split DWARF Objects (Informative)]{Split DWARF Objects (Informative)}
+\label{app:splitdwarfobjectsinformative}
+
+With the traditional DWARF format, debug information is designed
+with the expectation that it will be processed by the linker to
+produce an output binary with complete debug information, and
+with fully-resolved references to locations within the
+application. For very large applications, however, this approach
+can result in excessively large link times and excessively large
+output files. 
+
+Several vendors have independently developed
+proprietary approaches that allow the debug information to remain
+in the relocatable object files, so that the linker does not have
+to process the debug information or copy it to the output file.
+These approaches have all required that additional information be
+made available to the debug information consumer, and that the
+consumer perform some minimal amount of relocation in order to
+interpret the debug info correctly. The additional information
+required, in the form of load maps or symbol tables, and the
+details of the relocation are not covered by the DWARF
+specification, and vary with each vendor's implementation.
+
+These limitations are removed by the design described here.
+
+\section{Overview}
+\label{app:splitoverview}
+\DWARFVersionV{} introduces an optional set of debugging sections
+that allow the compiler to partition the debugging information
+into a set of (small) sections that require link-time relocation
+and a set of (large) sections that do not. The sections that
+require relocation are written to the relocatable object file as
+usual, and are linked into the final executable. The sections
+that do not require relocation, however, can be written to the
+relocatable object (.o) file but ignored by the linker, or they
+can be written to a separate DWARF object (dwo{}) file.
+
+\needlines{4}
+The optional set of debugging sections includes the following:
+\begin{itemize}
+\item
+\dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} DIE and
+its descendants. This is the bulk of the debugging
+information for the compilation unit that is normally found
+in the \dotdebuginfo{} section.
+\item
+\dotdebugtypesdwo{} - Contains the \DWTAGtypeunit{} DIEs and
+their descendants. This is the bulk of the debugging
+information for the type units that is normally found in the
+\dotdebugtypes{} section.
+\item
+\dotdebugabbrevdwo{} - Contains the abbreviations tables used by
+the \dotdebuginfodwo{} and \dotdebugtypesdwo{} sections.
+\item
+\dotdebuglocdwo{} - Contains the location lists referenced by
+the debugging information entries in the \dotdebuginfodwo{}
+section. This contains the location lists normally found in 
+the \dotdebugloc{} section,
+with a slightly modified format to eliminate the need for
+relocations.
+\item
+\dotdebugstrdwo{} - Contains the string table for all indirect
+strings referenced by the debugging information in the
+\dotdebuginfodwo{} and \dotdebugtypesdwo{} sections.
+\item
+\dotdebugstroffsetsdwo{} - Contains the string offsets table
+for the strings in the \dotdebugstrdwo{}{} section.
+\item
+\dotdebugmacinfodwo{} - Contains macro definition information,
+normally found in the \dotdebugmacinfo{} section.
+\item
+\dotdebuglinedwo{} - Contains skeleton line tables for the type
+units in the \dotdebugtypesdwo{} section. These line tables
+contain only the directory and files 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.
+\end{itemize}
+
+In order for the consumer to locate and process the debug
+information, the compiler must produce a small amount of debug
+information that passes through the linker into the output
+binary. A skeleton \dotdebuginfo{} section for each compilation unit
+contains a reference to the corresponding ".o" or ".dwo"
+file, and the \dotdebugline{} section (which is typically small
+compared to the \dotdebuginfo{} and \dotdebugtypes{} sections) is
+linked into the output binary, as is the new \dotdebugaddr{}
+section.
+
+\needlines{6}
+The debug sections that continue to be linked into the
+output binary include the following:
+\begin{itemize}
+\item
+\dotdebugabbrev{} - Contains the abbreviation codes used by the
+skeleton \dotdebuginfo{} section.
+\item
+\dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
+but no children.
+\item
+\dotdebugstr{} - Contains any strings referenced by the skeleton
+\dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
+\item
+\dotdebugstroffsets{} - Contains the string offsets table for
+the strings in the \dotdebugstr{} section.
+\item
+\dotdebugaddr{} - Contains references to loadable sections,
+indexed by attributes of form \DWFORMaddrx{} or location
+expression \DWOPaddrx{} opcodes.
+\item
+\dotdebugline{} - Contains the line number tables, unaffected by
+this design. (These could be moved to the .dwo file, but in
+order to do so, each \DWLNEsetaddress{} opcode would need to
+be replaced by a new opcode that referenced an entry in the
+\dotdebugaddr{} section. Furthermore, leaving this section in the
+.o file allows many debug info consumers to remain unaware of
+.dwo files.)
+\item
+\dotdebugframe{} - Contains the frame tables, unaffected by this
+design.
+\item
+\dotdebugranges{} - Contains the range lists, unaffected by this
+design.
+\item
+\dotdebugpubnames{} - Contains the public names for use in
+building an index section. This section has the same
+format and use as always. The section header refers to a
+compilation unit offset, which is the offset of the
+skeleton compilation unit in the \dotdebuginfo{} section.
+\item
+\dotdebugpubtypes{} - Contains the public types for use in
+building an index section. This section has the same
+format and use as always. The section header refers to a
+compilation unit offset, which is the offset of the
+skeleton compilation unit in the \dotdebuginfo{} section.
+\item
+\dotdebugaranges{} - Contains the accelerated range lookup table
+for the compilation unit, unaffected by this design.
+\end{itemize}
+
+\needlines{6}
+The skeleton \DWTAGcompileunit{} DIE has the following attributes:
+\autocols[0pt]{c}{3}{l}{
+\DWATcompdir{},
+\DWATdwoname{} (new),
+\DWATdwoid{} (new),
+\DWATstmtlist{},
+\DWATlowpc{} \dag,
+\DWAThighpc{} \dag,
+\DWATranges{} \dag,
+\DWATrangesbase{},
+\DWATaddrbase{}
+}
+\dag{} If \DWATranges{} is present, \DWATlowpc{} and \DWAThighpc{} are
+not used, and vice versa.
+
+All other attributes of the compilation unit DIE are moved to
+the full DIE in the \dotdebuginfodwo{} section.
+
+Because of other improvements in \DWARFVersionV, most of the
+relocations that would normally be found in the \dotdebuginfodwo{}
+and \dotdebugtypesdwo{} sections is moved to the \dotdebugaddr{} and
+\dotdebugstroffsetsdwo{} sections. Those in the
+\dotdebugstroffsetsdwo{} sections are simply be omitted because the
+DWARF information in those sections is not combined at link
+time, so no relocation is necessary. Similarly,
+many of the remaining relocations referring to range lists are
+eliminated. 
+
+The relocations that remain fall into the following categories:
+\begin{itemize}
+\item
+References from compilation unit and type unit headers to the
+\dotdebugabbrevdwo{} section. Because the new sections are not
+combined at link time, these references need no relocations.
+\item
+References from \DWTAGcompileunit{} DIEs to the
+\dotdebuglinedwo{} section, via \DWATstmtlist{}. This attribute
+remains in the skeleton \dotdebuginfo{} section, so no
+relocation in the \dotdebuginfodwo{} section is necessary.
+\item
+References from \DWTAGtypeunit{} DIEs to the skeleton
+\dotdebuglinedwo{} section, via \DWATstmtlist{}. Because the new
+sections are not combined at link time, these references need
+no relocations.
+\item
+References from \DWTAGcompileunit{} and \DWTAGtypeunit{} DIEs
+to the \dotdebugstroffsetsdwo{} section, via
+\DWATstroffsetsbase{}. Because the new sections are not
+combined at link time, the \DWATstroffsetsbase{} attribute
+is not required in a \dotdebuginfodwo{} or \dotdebugtypesdwo{}
+section.
+\item
+References from \DWTAGcompileunit{} DIEs to the \dotdebugaddr{}
+section, via \DWATaddrbase{}. This attribute remains in
+the skeleton \dotdebuginfo{} section, so no relocation in the
+\dotdebuginfodwo{} section is necessary.
+\needlines{4}
+\item
+References from \DWTAGcompileunit{} DIEs to the \dotdebugranges{}
+section, via \DWATrangesbase{}. This attribute remains in
+the skeleton \dotdebuginfo{} section, so no relocation in the
+\dotdebuginfodwo{} section is necessary.
+\item
+References from the \dotdebuglocdwo{} section to machine addresses
+via a location list entry or a base address selection entry.
+With a minor change to the location list entry format,
+described below, these relocations are also eliminated.
+\end{itemize}
+
+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
+into the \dotdebugaddr{} section. Each location list entry begins
+with a single byte identifying the entry type:
+\begin{itemize}
+\item
+\DWLLEendoflistentry{} (0) indicates an end-of-list entry,
+\item
+\DWLLEbaseaddressselectionentry{} (1) indicates a base address
+selection entry, 
+\item
+\DWLLEstartendentry{} (2) indicates a normal
+location list entry providing start and end addresses,
+\item
+\DWLLEstartlengthentry{} (3) indicates a normal location list
+entry providing a start address and a length, and
+\item
+\DWLLEoffsetpairentry{} (4) indicates a normal location list
+entry providing start and end offsets relative to the base
+address. 
+\end{itemize}
+An end-of-list entry has no further data. A base address
+selection entry contains a single unsigned LEB128 number
+following the entry type byte, which is an index into the
+\dotdebugaddr{} section that selects the new base address for
+subsequent location list entries. A start/end entry contains two
+unsigned LEB128 numbers following the entry type byte, which are
+indices into the \dotdebugaddr{} section that select the beginning
+and ending addresses. A start/length entry contains one unsigned
+LEB128 number and a 4-byte unsigned value (as would be
+represented by the form code \DWFORMdatafour). The first number
+is an index into the \dotdebugaddr{} section that selects the
+beginning offset, and the second number is the length of the
+range. Addresses fetched from the \dotdebugaddr{} section are not
+relative to the base address. An offset pair entry contains two
+4-byte unsigned values (as would be represented by the form code
+\DWFORMdatafour){}, treated as the beginning and ending offsets,
+respectively, relative to the base address. As in the \dotdebugloc{}
+section, the base address is obtained either from the nearest
+preceding base address selection entry, or, if there is no such
+entry, from the compilation unit base address (as defined in
+Section 3.1.1). For the latter three types (start/end,
+start/length, and offset pair), the two operand values are
+followed by a location description as in a normal location list
+entry in the \dotdebugloc{} section.
+
+This design depends on having an index of debugging information
+available to the consumer. For name lookups, the consumer can use
+the \dotdebugpubnames{} and \dotdebugpubtypes{} sections (or an index
+built at link time based on the information in those sections),
+which will lead to a skeleton compilation unit. The
+\DWATcompdir{} and \DWATdwoname{} attributes in the skeleton
+compilation unit can then be used to locate the corresponding
+DWARF object file for the compilation unit. Similarly, for an
+address lookup, the consumer can use the \dotdebugaranges{} table,
+which will also lead to a skeleton compilation unit. For a file
+and line number lookup, the skeleton compilation units can be
+used to locate the line number tables.
+
+\section{Split DWARF Object Examples}
+\label{app:splitdwarfobjectexamples}
+
+TBD
\ No newline at end of file
index 7e0d371..99a7f7a 100644 (file)
@@ -2164,9 +2164,45 @@ a
 (see Section \refersec{chap:staticanddynamicvaluesofattributes})
 is the amount of storage need to hold a value of the file type.
 
+\section{Dynamic Type Entries and Properties}
+
+\subsection{Dynamic Type Entries}
+\textit{Some languages such as 
+\addtoindex{Fortran 90}, provide types whose values
+may be dynamically allocated or associated with a variable
+under explicit program control. However, unlike the related
+pointer type in \addtoindex{C} or 
+\addtoindex{C++}, the indirection involved in accessing
+the value of the variable is generally implicit, that is, not
+indicated as part of program source.}
+
+A dynamic type entry is used to declare a dynamic type that is 
+\doublequote{just like} another non-dynamic type without needing to
+replicate the full description of that other type.
+
+A dynamic type is represented by a debugging information entry
+with the tag \DWTAGdynamictypeTARG. If a name has been given to the
+dynamic type, then the dynamic type has a \DWATname{} attribute 
+whose value is a null-terminated string containing the dynamic
+type name as it appears in the source.
+       
+A dynamic type entry has a \DWATtype{} attribute whose value is a
+reference to the type of the entities that are dynamically allocated.
+       
+A dynamic type entry also has a \DWATdatalocation, and may also
+have \DWATallocated{} and/or \DWATassociated{} attributes as 
+described following (Section 5.15.1). The type referenced by the
+\DWATtype{} attribute must not have any of these attributes.
+
 \subsection{Dynamic Type Properties}
 \label{chap:dynamictypeproperties}
-\subsection{Data Location}
+\textit{
+The \DWATdatalocation, \DWATallocated{} and \DWATassociated{} 
+attributes described in this section can be used for any type, not
+just dynamic types.}
+
+\needlines{6}
+\subsubsection{Data Location}
 \label{chap:datalocation}
 
 \textit{Some languages may represent objects using descriptors to hold
@@ -2197,7 +2233,7 @@ calculation. For an example using
 for a \addtoindex{Fortran 90 array}, see 
 Appendix \refersec{app:fortranarrayexample}.}
 
-\subsection{Allocation and Association Status}
+\subsubsection{Allocation and Association Status}
 \label{chap:allocationandassociationstatus}
 
 \textit{Some languages, such as \addtoindex{Fortran 90},
@@ -2262,7 +2298,7 @@ pointer assignment.}
 arrays, 
 see Appendix \refersec{app:aggregateexamples}.}
 
-\subsection{Array Rank}
+\subsubsection{Array Rank}
 \label{chap:DWATrank}
 \addtoindexx{array!assumed-rank}
 \addtoindexx{assumed-rank array|see{array, assumed-rank}}
@@ -2308,7 +2344,7 @@ fashion.
 \label{chap:templatealiasentries}
 
 \textit{
-In addtoindex{C++}, a template alias is a form of typedef that has template
+In \addtoindex{C++}, a template alias is a form of typedef that has template
 parameters.  DWARF does not represent the template alias definition
 but does represent instantiations of the alias.
 }