Working copy for backup...
authorRon Brender <ron.brender@gmail.com>
Fri, 31 Jul 2015 14:26:34 +0000 (10:26 -0400)
committerRon Brender <ron.brender@gmail.com>
Fri, 31 Jul 2015 14:26:34 +0000 (10:26 -0400)
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/generaldescription.tex
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/splitobjects.tex
dwarf5/latexdoc/typeentries.tex

index 7038ebf..296aae5 100644 (file)
@@ -15,6 +15,8 @@ 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
+7/28-29/2015    & 150623.1 (MD5 digest), new F.3 (.dwp files), remove trial Selected Glossary, \\
+                & more editorial work X \\
 6/30-7/14/2015  & Revise 3.1 Compilation Units, replace Figure 6.1, \\
                 & add trial Selected Glossary appendix, more editorial work IX \\
 6/24-29/2015    & More editorial work VIII \\
index 4ee7b05..f742764 100644 (file)
@@ -274,9 +274,9 @@ the skeleton compilation unit uses the \DWFORMstrx{} form.
 \end{itemize}
 The attributes contained in the skeleton compilation
 unit can be used by a DWARF consumer to find the 
-\bb
+
 split or hybrid 
-\eb
+
 DWARF object file that contains the second partition.
 
 \subsubsection{Second Partition (Unlinked or In \texttt{.dwo} File)}
@@ -408,7 +408,10 @@ 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
+\bb
+unit ID 
+\eb
+(\DWATdwoid) for compilation units, or by type
 signature for type units:
 \begin{alltt}
     \dotdebugcuindex
@@ -417,7 +420,11 @@ signature for type units:
 
 \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
+compilation unit
+\bb
+ID 
+\eb
+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.
 
@@ -451,8 +458,8 @@ sections:
 \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.
+Both index sections have the same format, and serve to map an
+8-byte signature to a set of contributions to the debug sections.
 Each index 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
@@ -510,20 +517,29 @@ 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 $X$,
+\bb
+Given an 8-byte compilation unit ID
+\eb
+or type signature $X$,
 an entry in the hash table is located as follows:
 \begin{enumerate}[1. ]
-\item Calculate a primary hash $H = X\ \&\ MASK(k)$, where $MASK(k)$ is a
-    mask with the low-order $k$ bits all set to 1.
+\bb
+\item Define $REP(X)$ to be the value of $X$ interpreted as an 
+      unsigned 64-bit integer in the target byte order.
 
-\item Calculate a secondary hash $H' = (((X>>32)\ \&\ MASK(k))\ |\ 1)$.
+\item Calculate a primary hash $H = REP(X)\ \&\ MASK(k)$, where
+\eb 
+      $MASK(k)$ is a mask with the low-order $k$ bits all set to 1.
+\bb
+\item Calculate a secondary hash $H' = (((REP(X)>>32)\ \&\ MASK(k))\ |\ 1)$.
+\eb
 
 \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.
+      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\ S$. Repeat at Step 3.
+\item Let $H = (H + H')\ modulo\ S$. Repeat at Step 4.
 \end{enumerate}
 
 Because $S > U$, and $H'$ and $S$ are relatively prime, the search is
@@ -930,9 +946,9 @@ The value in this field is \versiondotdebuginfo.
 \addttindexx{unit\_type}
 A 1-byte unsigned integer identifying this unit as a compilation unit.
 The value of this field is 
-\DWUTcompile{} for a {normal compilation} unit or
-\DWUTpartial{} for a {partial compilation} unit
-(see Section \refersec{chap:normalandpartialcompilationunitentries}).
+\DWUTcompile{} for a full compilation unit or
+\DWUTpartial{} for a partial compilation unit
+(see Section \refersec{chap:fullandpartialcompilationunitentries}).
 
 \textit{This field is new in \DWARFVersionV.}
 
@@ -1024,7 +1040,7 @@ offset portion of an address.
 \item \texttt{type\_signature} (8-byte unsigned integer) \\
 \addttindexx{type\_signature}
 \addtoindexx{type signature}
-A unique 64-bit signature (see Section 
+A unique 8-byte signature (see Section 
 \refersec{datarep:typesignaturecomputation})
 of the type described in this type
 unit.  
@@ -1911,7 +1927,7 @@ information type entry that has been placed in its own
 \addtoindex{type unit}. This type of 
 reference (\DWFORMrefsigeightTARG) is the
 \addtoindexx{type signature}
-64-bit type signature 
+8-byte type signature 
 (see Section \refersec{datarep:typesignaturecomputation}) 
 that was computed for the type. 
 
@@ -2825,59 +2841,9 @@ Table \refersec{tab:discriminantdescriptorencodings}.
 \needlines{6}
 \section{Name Index Table}
 \label{datarep:nameindextable}
-Each name index table in the \dotdebugnames{} section 
-begins with a header consisting of:
-\begin{enumerate}[1. ]
-\item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\
-\addttindexx{unit\_length}
-A 4-byte or 12-byte initial length field that 
-contains the size in bytes of this contribution to the \dotdebugnames{} 
-section, not including the length field itself
-(see Section \refersec{datarep:initiallengthvalues}).
-
-\item \texttt{version} (\HFTuhalf) \\
-A 2-byte version number\addtoindexx{version number!name index table} 
+The \addtoindexi{version number}{version number!name index table}
+in the name index table header is \versiondotdebugnames{}
 (see Appendix \refersec{app:dwarfsectionversionnumbersinformative}). 
-This number is specific to the name index table and is
-independent of the DWARF version number.
-
-The value in this field is \versiondotdebugnames.
-
-\item padding (\HFTuhalf) \\
-
-\item \texttt{comp\_unit\_count} (\HFTuword) \\
-The number of CUs in the CU list.
-
-\item \texttt{local\_type\_unit\_count} (\HFTuword) \\
-The number of TUs in the first TU list.
-
-\item \texttt{foreign\_type\_unit\_count} (\HFTuword) \\
-The number of TUs in the second TU list.
-
-\item \texttt{bucket\_count} (\HFTuword) \\
-The number of hash buckets in the hash lookup table. 
-If there is no hash lookup table, this field contains 0.
-
-\item \texttt{name\_count} (\HFTuword) \\
-The number of unique names in the index.
-
-\item \texttt{abbrev\_table\_size} (\HFTuword) \\
-The size in bytes of the abbreviations table.
-
-\item \texttt{augmentation\_string\_size} (\HFTuword) \\
-The size in bytes of the augmentation string. This value is 
-rounded up to a multiple of 4.
-
-\item \texttt{augmentation\_string} (\HFTaugstring) \\
-A vendor-specific augmentation string, which provides additional 
-information about the contents of this index. If provided, the string
-begins with a 4-character vendor ID. The remainder of the
-string is meant to be read by a cooperating consumer, and its
-contents and interpretation are not specified here. The
-string is padded with null characters to a multiple of
-four bytes in length.
-
-\end{enumerate}
 
 The name index attributes and their encodings are listed in Table \referfol{datarep:indexattributeencodings}.
 
@@ -3535,7 +3501,7 @@ compare two type signatures to check for equality.}
 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}
-hash of a flattened description of the type. The flattened
+digest of a flattened description of the type. The flattened
 description of the type is a byte sequence derived from the
 DWARF encoding of the type as follows:
 \begin{enumerate}[1. ]
@@ -3754,8 +3720,8 @@ example, a constant value should be preferred to a location
 expression when possible.)
 
 Once the string S has been formed from the DWARF encoding,
-an \MDfive{} hash is computed for the string and the 
-least significant 64 bits are taken as the type signature.
+an 16-byte \MDfive{} digest is computed for the string and the 
+last eight bytes are taken as the type signature.
 
 \textit{The string S is intended to be a flattened representation of
 the type that uniquely identifies that type (that is, a different
@@ -3803,7 +3769,7 @@ declaration of the type.}
 \DWATdeclcolumn{} attributes are not included because they
 may vary from one source file to the next, and would prevent
 two otherwise identical type declarations from producing the
-same \MDfive{} hash.}
+same \MDfive{} digest.}
 
 \item \textit{The \DWATobjectpointer{} attribute is not included 
 because the information it provides is not necessary for the 
@@ -3826,7 +3792,7 @@ and replacing the function definition in the type with a non-defining
 declaration of the function (as if the function had been defined out of 
 line).}
 
-An example that illustrates the computation of an \MDfive{} hash may be found in 
+An example that illustrates the computation of an \MDfive{} digest may be found in 
 Appendix \refersec{app:usingtypeunits}.
 
 \section{Name Table Hash Function}
index 9c344b2..6b226d2 100644 (file)
@@ -3,14 +3,12 @@
 % 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}{July 14, 2015}
+\newcommand{\docdate}{July 29, 2015}
 %
 \usepackage{ifthen}
 \newcommand{\ifthen}[2]{\ifthenelse{#1}{#2}{}}
 \newboolean{isdraft}\setboolean{isdraft}{true}
 \newcommand{\draftmark}{\ifthenelse{\boolean{isdraft}}{*** DRAFT ***}{}}
-\newboolean{Trial1ReUnits}\setboolean{Trial1ReUnits}{true}
-\newboolean{Trial2ReGlossary}\setboolean{Trial2ReGlossary}{true}
 %
 \usepackage[T1]{fontenc}
 \usepackage{palatino}
@@ -210,12 +208,13 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \newcommand{\isdefined}[1]{\not{\isundefined{#1}}}
 
 % Preferred changebar asliases
-\newcommand{\bb}{\cbstart}      % Begin bar
-\newcommand{\eb}{\cbend}        % End bar
+\newcommand{\bb}{\cbstart}      % Begin (change) bar
+\newcommand{\eb}{\cbend}        % End (change) bar
 
 % Define commands for all of the DWARF names (DW\_*, .debug_*, a few others)
 %
 \newcommand{\definition}[1]{\textcolor{red!80!black}{#1}}
+\newcommand{\definitionx}[1]{\definition{\addtoindex{#1}}}
 \include{dwarfnamecmds}
 
 %--- Begin the document pages
@@ -345,10 +344,9 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \include{splitobjects}                 %\emptypage
 \include{sectionversionnumbers}         \emptypage
 \include{gnulicense}                    \emptypage
-\ifthenelse{\boolean{Trial2ReGlossary}}
-    {
-    \include{selectedglossary}          %\emptypage
-    }{}
+
+% Maybe someday the selected glossary concept will be of interest...
+%\include{selectedglossary}             %\emptypage
 
 \printindex
 
index 7b19227..48895ed 100644 (file)
 \newcommand{\typeunitset}{\addtoindex{type unit set}}
 \newcommand{\byteorder}{\addtoindex{byte order}}
 \newcommand{\associatedcompilationunit}{\addtoindex{associated compilation unit}}
+\newcommand{\CUsignature}{\addtoindex{compilation unit ID}}
+\newcommand{\TUsignature}{\addtoindex{type unit signature}}
 \newcommand{\chkmk}{{\footnotesize$\surd$}}             % Check mark
 %
 % Anti-ligature commands added because \/ and {} don't work for unknown reasons
index a873b79..e7d0495 100644 (file)
@@ -454,7 +454,7 @@ The attributes are listed in Table \referfol{tab:attributenames}.
 \DWATdwoidTARG
 &\livelinki{chap:DWATdwoidforunit}
         {Signature for compilation unit}
-        {split DWARF object file!unit signature} \\
+        {split DWARF object file!unit ID} \\
 \DWATdwonameTARG
 &\livelinki{chap:DWATdwonameforunit}
         {Name of split DWARF object file}
@@ -900,7 +900,7 @@ entry in any compilation unit, including one different from
 the unit containing the reference. The third type of reference
 is an indirect reference to a 
 \addtoindexx{type signature}
-type definition using a 64-bit \mbox{signature} 
+type definition using a 8-byte \mbox{signature} 
 for that type. The fourth type of reference is a reference from within the 
 \dotdebuginfo{} section of the executable or shared object file to
 a debugging information entry in the \dotdebuginfo{} section of 
index 8970dbe..40eac16 100644 (file)
@@ -90,6 +90,18 @@ declaration in the \dotdebuginfo{} section.
 The name index may also contain an optional hash table for faster
 lookup.
 
+\bb
+A relocatable object file may contain a "per-CU" index, which
+provides an index to the names defined in that compilation
+unit.
+
+An executable or shareable object file may contain either a collection of
+"per-CU" indexes, simply copied from each relocatable object
+file, or the linker may produce a "per-module" index by
+combining the per-CU indexes into a single index that covers
+the entire load module.
+\eb
+
 \subsubsection{Contents of the Name Index}
 \label{chap:contentsofthenameindex}
 The name index must contain an entry for each DIE that defines a
@@ -170,7 +182,7 @@ Figure \referfol{fig:nameindexlayout}.
 \end{enumerate}
 
 \begin{figure}[p]
-\bb
+
 \begin{center}
 \newcommand{\thisblue}{blue!10}
 \newcommand{\thisyellow}{yellow!20}
@@ -333,7 +345,7 @@ Figure \referfol{fig:nameindexlayout}.
 \end{center}
 \caption{Name Index Layout}
 \label{fig:nameindexlayout}
-\eb
+
 \end{figure}
 
 The formats of the header and the hash lookup table are described
@@ -415,17 +427,21 @@ attributes for both CU and (foreign) TU. For such entries, the CU
 attribute gives the consumer a reference to the CU that may be used to
 locate a \splitDWARFobjectfile{} that contains the type unit.
 
-The type hash attribute, not to be confused with the type signature
+\bb
+\textit{The type hash attribute, not to be confused with the type signature
 for a TU, may be provided for type entries whose declarations are not
 in a type unit, for the convenience of link-time or post-link
 utilities that wish to de-duplicate type declarations across
 compilation units. The type hash, however, is computed by the
-same method as specified for type signatures.
+same method as specified for type signatures.}
+\eb
 
 The last entry for each name is followed by a zero byte that
 terminates the list. There may be gaps between the lists.
 
-\subsubsection{Per-CU versus Per-Module Indexes \textit{(Non-Normative)}}
+\bb
+\subsubsection{Per-CU versus Per-Module Indexes}
+\eb
 \label{chap:percuvspermoduleindexes}
 \textit{In a per-CU index, the CU list may have only a single entry, 
 and index entries may omit the CU attribute. (Cross-module or link-time
@@ -548,7 +564,7 @@ The total number of entries in the list is given by
 
 \subsubsubsection{List of Foreign TUs}
 The list of foreign TUs immediately follows the list of local TUs.
-Each entry in the list is an 64-bit type signature (as described by
+Each entry in the list is a 8-byte type signature (as described by
 \DWFORMrefsigeight).
 
 The number of entries in the list is given by \texttt{foreign\_type\_unit\_count}.
@@ -577,7 +593,11 @@ Each bucket contains the index of an entry in the hashes array. The
 hashes array is indexed starting at 1, and an empty bucket is
 represented by the value 0.
 
-The hashes array contains a list of the full hash values for each
+The hashes array contains a 
+\bb
+sequence
+\eb
+of the full hash values for each
 symbol. All symbols that have the same index into the bucket list 
 follow one another in the hashes array, and the indexed entry in 
 the bucket list refers to the first symbol. 
index 5b62eb5..cfd8b0f 100644 (file)
@@ -10,10 +10,6 @@ as bounded by ranges of text addresses within the program.
 \section{Unit Entries}
 \label{chap:unitentries}
 
-\ifthenelse{\boolean{Trial1ReUnits}}
-%%%%%%%%%%%%%%%%%%%%\then
-{
-\bb
 A DWARF object file is an object file that contains one or more 
 DWARF compilation units, of which there are these kinds:
 \addtoindexx{unit|see {compilation unit}} 
@@ -25,7 +21,10 @@ related partial compilation units and/or type units.
 
 \item A \definition{partial compilation unit} describes
 a part of a compilation (generally corresponding to an
-included file) which is imported into one or more 
+\bb
+imported module) 
+\eb
+which is imported into one or more 
 related full compilation units.
 
 \item A \definition{type unit} is a specialized unit
@@ -63,12 +62,15 @@ the conventional compilation units, a skeleton compilation unit
 is part of the same object file as the compiled code and data.}
 
 \begin{itemize}
-\item A \definition{split full compilation unit} describes
+\item A 
+\bb
+\definition{split compilation unit} describes
+\eb
 a complete compilation, possibly in combination with
 related type compilation units. It corresponds 
 to a specific skeleton compilation unit.
 
-\item A \definition{split type compilation unit} is a specialized
+\item A \definition{split type unit} is a specialized
 compilation unit that represents a type whose description may
 be usefully shared by multiple other units.
 
@@ -83,9 +85,10 @@ unit may be logically incorporated into another compilation unit
 using an \addtoindex{imported unit entry}
 (see Section \refersec{chap:importedunitentries}).}
 
-\textit{Split compilation units and partial compilation units
-serve similar purposes as a means to promote sharing and
-compression of DWARF information; thus, a combined split partial
+\textit{A
+\bb
+combined split and partial
+\eb
 compilation unit kind is not defined.}
 
 \textit{In the remainder of this document, the word 
@@ -132,76 +135,6 @@ portion of a compilation. A full compilation unit can also
 function in a manner similar to a partial compilation unit
 in some cases.}
 
-\eb
-}
-%%%%%%%%%%%%%%%%%%%%\else
-{
-An object file may contain one or more compilation units,
-of which there are
-\addtoindexx{unit|see {compilation unit}} 
-\addtoindexx{compilation unit}
-these kinds:
-normal compilation units,
-partial compilation units, 
-type units,\addtoindexx{type unit} and
-skeleton units. A 
-\addtoindex{partial compilation unit}
-is related to one or more other compilation units that
-import it.  
-A skeleton unit contains only a subset of the attributes of 
-a full normal or partial compilation unit plus two attributes 
-used to locate the DWARF object file where the full 
-compilation unit can be found.
-A \addtoindex{type unit} represents a single complete type 
-in a compilation unit of its own.
-Either a normal compilation unit or a 
-\addtoindex{partial compilation unit}
-may be logically incorporated into another
-compilation unit using an 
-\addtoindex{imported unit entry}
-(see Section \refersec{chap:importedunitentries}).
-
-
-\subsection[Normal and Partial CU Entries]{Normal and Partial Compilation Unit Entries}
-\label{chap:normalandpartialcompilationunitentries}
-A \addtoindex{normal compilation unit}\addtoindexx{compilation unit!normal} 
-is represented by a debugging information entry with the tag 
-\DWTAGcompileunitTARG. 
-A \addtoindex{partial compilation unit}\addtoindexx{compilation unit!partial} 
-is represented by a debugging information entry with the tag 
-\DWTAGpartialunitTARG.
-
-\needlines{6}
-In a simple normal compilation, a single compilation unit with
-the tag 
-\DWTAGcompileunit{} represents a complete object file
-and the tag 
-\DWTAGpartialunit{} is not used. 
-In a compilation
-employing the DWARF space compression and duplicate elimination
-techniques from 
-Appendix \refersec{app:usingcompilationunits}, 
-multiple compilation units using
-the tags 
-\DWTAGcompileunit{} and/or 
-\DWTAGpartialunit{} are
-used to represent portions of an object file.
-
-\textit{A normal compilation unit typically represents the text and
-data contributed to an executable by a single relocatable
-object file. It may be derived from several source files,
-including pre-processed header files. 
-A \addtoindex{partial compilation unit} typically represents a part of the text
-and data of a relocatable object file, in a manner that can
-potentially be shared with the results of other compilations
-to save space. It may be derived from an \doublequote{include file,}
-template instantiation, or other implementation\dash dependent
-portion of a compilation. A normal compilation unit can also
-function in a manner similar to a partial compilation unit
-in some cases.}
-}
-%%%%%%%%%%%%%%%%%%%%%\endif
-
 A compilation unit entry owns debugging information
 entries that represent all or part of the declarations
 made in the corresponding compilation. In the case of a
@@ -532,20 +465,18 @@ Section \refersec{datarep:splitdwarfobjectfiles}), the
 compilation unit in the \dotdebuginfo{} section is a "skeleton"
 compilation unit with the tag \DWTAGcompileunit, which contains 
 \DWATdwoname{} and \DWATdwoid{} attributes as well as a subset of the
-\bb
 attributes of a full or partial compilation unit. In general,
 it contains those attributes that are necessary for the consumer
 to locate the object file where the split full compilation unit
-\eb
 can be found, and for the consumer to interpret references to
 addresses in the program. 
 
-\bb
+
 A skeleton compilation unit has no children.
 
 A skeleton compilation unit has \DWATdwoname{} and 
 \DWATdwoid{} attributes:
-\eb
+
 \begin{enumerate}[1. ]
 
 \item
@@ -560,23 +491,30 @@ compilation unit.
 \item
 \livetarg{chap:DWATdwoidforunit}{}
 A \DWATdwoidDEFN{} attribute\addtoindexx{unit identification attribute}
-whose implementation-defined integer constant value
+whose implementation-defined integer constant value,
+\bb
+known as the \CUsignature,
+\eb
 provides unique identification of this compilation unit
 as well as the associated split compilation unit in the
-\bb
 object file named in the \DWATdwoname{}
 attribute. For simplicity, the \DWATdwoidNAME{} attributes
 in the skeleton compilation unit and the corresponding
 split full compilation unit 
 (see Section \refersec{chap:splitfullcompilationunitentries})
-\eb
 must use the same form to encode this identification value.
-\end{enumerate}
 
 \bb
+\textit{The means of determining a \CUsignature{} does not 
+need to be similar or related to the means of determining a
+\TUsignature.}
+\eb 
+
+\end{enumerate}
+
 A skeleton compilation unit may have additional
 attributes from among the following:
-\eb
+
 \begin{enumerate}[1. ]
 \addtocounter{enumi}{2}
 \item
@@ -634,15 +572,10 @@ found the correct object file.
 necessary to interpret the contents
 of the corresponding \splitDWARFobjectfile.}
 
-\bb
 \textit{The \DWATbasetypes{} attribute is not defined for a
 skeleton compilation unit.}
-\eb
 
-\ifthenelse{\boolean{Trial1ReUnits}}
-%%%%%%%%%%%%%%%%%%%%\then
-{
-\bb
+
 \subsection{Split Full Compilation Unit Entries}
 \label{chap:splitfullcompilationunitentries}
 A \definition{split full compilation unit} is represented by a 
@@ -655,13 +588,23 @@ A split full compilation unit has a \DWATdwoid{} attribute:
 \begin{enumerate}[1. ]
 \item
 A \DWATdwoidDEFN{} attribute\addtoindexx{unit identification attribute}
-whose implementation-defined integer constant value
+whose implementation-defined integer constant value,
+\bb
+known as the \CUsignature,
+\eb
 provides unique identification of this compilation unit
 as well as the associated skeleton compilation unit.
 For simplicity, the \DWATdwoidNAME{} attributes in the 
 split compilation unit and the associated skeleton 
 compilation unit must use the same form to encode the 
 identification value.
+
+\bb
+\textit{The means of determining a \CUsignature{} does not 
+need to be similar or related to the means of determining a
+\TUsignature.}
+\eb 
+
 \end{enumerate}
 
 A split full compilation unit may also have additional 
@@ -703,8 +646,7 @@ split full compilation unit entry but instead are inherited
 
 \textit{The \DWATbasetypes{} attribute is not defined for a
 split full compilation unit.}
-\eb
-}{}
+
 
 \needlines{6}
 \subsection{Type Unit Entries}
@@ -716,17 +658,15 @@ An object file may contain any number of separate type
 unit entries, each representing a single complete type
 definition. 
 Each \addtoindex{type unit} must be uniquely identified by
-a 64-bit signature, stored as part of the type unit, which
+an 8-byte signature, stored as part of the type unit, which
 can be used to reference the type definition from debugging
 information entries in other compilation units and type units.
-\ifthenelse{\boolean{Trial1ReUnits}}
-{\bb
+
 Conventional and split type units are identical except for
 the sections in which they are represented 
 (see \refersec{datarep:splitdwarfobjectfiles} for details).
 \addtoindexx{conventional type unit}
 \addtoindexx{split type unit}
-\eb}{}
 
 A type unit is represented by a debugging information entry
 with the tag \DWTAGtypeunitTARG. 
@@ -759,12 +699,10 @@ may be referenced by the \DWATdeclfile{} attribute of the
 type or part of its description.} 
 
 \textit{In an object file with a conventional compilation 
-\bb
 unit entry, the type unit entries may refer to (share) the 
-\eb
 line number table used by the compilation unit. In a type 
-unit located in a split compilation unit,
-the \DWATstmtlistNAME{} attribute refers to a "specialized"
+unit located in a split compilation unit, the 
+\DWATstmtlistNAME{} attribute refers to a \doublequote{specialized}
 line number table in the \dotdebuglinedwo{} section, which
 contains only the list of directories and file names.}
 
index f72caa0..5590042 100644 (file)
@@ -179,7 +179,7 @@ in both the skeleton DIE and the full DIE, so that a consumer
 can verify a match.
 
 \needlines{4}
-\bb
+
 Relocations are neither necessary nor useful in .dwo files, because the
 .dwo files contain only debugging information that does not need to be
 processed by a linker. Relocations are rendered unnecessary via
@@ -206,13 +206,13 @@ specified by the \DWATrangesbase{} attribute (which is placed in the
 skeleton compilation unit in the \texttt{.o} file).
 
 \end{enumerate}
-\eb
+
 
 Table \refersec{tab:unitattributesbyunitkind} summarizes which
 attributes are defined for use in the various kind of compilation
 units.
 
-\bb
+
 
 \begin{table}[h]
 \caption{Unit Attributes by Unit Kind}
@@ -250,7 +250,7 @@ units.
 \end{tabular}
 \end{table}
 
-\eb
+
 
 \needlines{8}
 The split dwarf object file design depends on having an index of 
@@ -861,4 +861,220 @@ address range.
 \section{DWARF Package File Example}
 \label{app:dwarfpackagefileexample}
 \addtoindexx{DWARF duplicate elimination!examples}
-[TBD]
+
+\bb
+A \definitionx{DWARF package file} is a collection of split 
+DWARF object files.
+In general, it will be much smaller than the sum of the split
+DWARF object files, because the packaging process removes duplicate
+type units and merges the string tables. Aside from those two
+optimizations, however, each compilation unit and each type unit
+from a split DWARF object file is copied verbatim into the package
+file.
+
+The package file contains the same set of sections as a split
+DWARF object file, plus two additional sections described below.
+
+The packaging utility, like a linker, combines sections of the
+same name by concatenation. While a split DWARF object may
+contain multiple \dotdebuginfodwo{} sections, one for the
+compilation unit, and one for each type unit, a package file
+contains a single \dotdebuginfodwo{} section. The combined
+\dotdebuginfodwo{} section contains each compilation unit and one
+copy of each type unit (discarding any duplicate type
+signatures).
+
+As part of merging the string tables, the packaging utility
+treats the \dotdebugstrdwo{} and \dotdebugstroffsetsdwo{}
+sections specially. Rather than
+combining them by simple concatenation, it instead builds a new
+string table consisting of the unique strings from each input
+string table. Because all references to these strings use the
+\DWFORMstrx{} form, the packaging utility only needs to adjust the
+string offsets in each \dotdebugstroffsetsdwo{} contribution after
+building the new \dotdebugstrdwo{} section.
+
+Each compilation unit or type unit consists of a set of
+inter-related contributions to each section in the package file.
+For example, a compilation unit may have contributions in
+\dotdebuginfodwo{}, \dotdebugabbrevdwo{}, \dotdebuglinedwo{},
+\dotdebugstroffsetsdwo{}, and so on. In order to maintain the ability 
+for a consumer to follow references between these sections, the
+package file contains two additional sections: a compilation unit
+(CU) index, and a type unit (TU) index. These indexes allow a
+consumer to look up a compilation unit (by its \CUsignature) or 
+a type unit (by its \TUsignature), and locate each contribution 
+that belongs to that unit.
+
+As an example, consider a package file, \texttt{demo.dwp}, formed by
+combining \texttt{demo1.dwo} and \texttt{demo2.dwo} from the previous example
+(see Appendix \refersec{app:splitdwarfobjectfileexample}). The
+resulting package file would contain the sections shown in Table
+\refersec{fig:sectionsandcontributionsinapackagefile}, 
+with contributions from each input file as shown.
+
+\begin{table}[h]
+\caption{Sections and contributions in a package file}
+\label{fig:sectionsandcontributionsinapackagefile}
+\begin{center}
+\begin{tabular}{P{4.7cm}|P{8cm}}
+\hline
+\bfseries Target \texttt{.dwp} section & \bfseries Source of section contributions \\
+\hline
+  \dotdebugabbrevdwo{}
+&    \dotdebugabbrevdwo{} from \texttt{demo1.dwo} \newline
+     \dotdebugabbrevdwo{} from \texttt{demo2.dwo} \\
+\hline \newline
+  \dotdebuginfodwo{} \newline (for the compilation units and type units)
+&    compilation unit from \texttt{demo1.dwo} \newline
+     compilation unit from \texttt{demo2.dwo} \newline
+     type unit for class \texttt{Box} from \texttt{demo1.dwo}   \newline
+     type unit for class \texttt{Point} from \texttt{demo1.dwo} \newline
+     type unit for class \texttt{Line} from \texttt{demo2.dwo}  \\
+\hline
+  \dotdebuglocdwo{}
+&    \dotdebuglocdwo{} from \texttt{demo1.dwo} \newline
+     \dotdebuglocdwo{} from \texttt{demo2.dwo} \\
+\hline
+  \dotdebuglinedwo{}
+&    \dotdebuglinedwo{} from \texttt{demo1.dwo} \newline
+     \dotdebuglinedwo{} from \texttt{demo2.dwo} \\
+\hline
+  \dotdebugstroffsetsdwo{}
+&    \dotdebugstroffsetsdwo{} from \texttt{demo1.dwo}, \hspace*{6mm}adjusted \newline
+     \dotdebugstroffsetsdwo{} from \texttt{demo2.dwo}, \hspace*{6mm}adjusted \\
+\hline
+  \dotdebugstrdwo{}
+&    new merged string table \\
+\hline
+  \dotdebugcuindex
+&    new CU index \\
+\hline
+  \dotdebugtuindex
+&    new TU index \\
+\hline
+\end{tabular}
+\end{center}
+\end{table}
+
+\needlines{4}
+The \dotdebugabbrevdwo{}, \dotdebuglocdwo{} and \dotdebuglinedwo{}
+sections have been copied over from the two \texttt{.dwo} files as
+individual contributions to the corresponding sections in the
+\texttt{.dwp} file. A record of the offset of each contribution within 
+the combined section, and the size of each contribution is recorded
+as part of the CU and TU index sections.
+
+The \dotdebuginfodwo{} sections corresponding to each compilation
+unit have been copied as individual contributions to the combined
+\dotdebuginfodwo{} section, and one copy of each type unit has also
+been copied. The type units for class \texttt{Box} and class 
+\texttt{Point}, for example, are contained in both \texttt{demo1.dwo} 
+and \texttt{demo2.dwo}, but only one instance of each is copied into 
+the package file.
+
+The \dotdebugstrdwo{} sections from each file have been merged to
+form a new string table with no duplicates, requiring the
+adjustment of all references to those strings. The
+\dotdebugstroffsetsdwo{} sections from the \texttt{.dwo} files have 
+been copied as individual contributions, but the string table offset
+in each slot of those contributions has been adjusted to point to
+the correct offset in the merged string table.
+
+The \dotdebugcuindex{} and \dotdebugtuindex{} sections provide a
+directory to these contributions. 
+Table \referfol{fig:examplecuindexsection} shows an example CU
+index section containing the two compilation units from 
+\texttt{demo1.dwo} and \texttt{demo2.dwo}. The CU index shows that 
+for the compilation unit from \texttt{demo1.dwo}, with \CUsignature{} 
+\texttt{0x044e413b8a2d1b8f}, its contribution to the \dotdebuginfodwo{} 
+section begins at offset 0, and is 325 bytes long. For the compilation 
+unit from \texttt{demo2.dwo}, with \CUsignature{} 
+\texttt{0xb5f0ecf455e7e97e}, its contribution to the \dotdebuginfodwo{}
+section begins at offset 325, and is 673 bytes long.
+
+Likewise, we can find the contributions to the related sections.
+In Figure \referfol{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}, 
+we see that the \DWTAGvariable{} DIE at \texttt{7\$} has a
+reference to a location list at offset 0x49 (decimal 73). Because
+this is part of the compilation unit for \texttt{demo2.dwo}, with 
+unit signature \texttt{0xb5f0ecf455e7e97e}, we see that its contribution 
+to \dotdebuglocdwo{} begins at offset 84, so the location list from
+Figure F.8 can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
+the combined \dotdebuglocdwo{} section.
+
+\begin{table}[h]
+\caption{Example CU index section}
+\label{fig:examplecuindexsection}
+\begin{center}
+\begin{tabular}{lrrrrrr}
+\hline \\
+  \multicolumn{2}{l}{Version:}&                 5 &&&&\\
+  \multicolumn{2}{l}{Number of columns:}&       5 &&&&\\
+  \multicolumn{2}{l}{Number of used entries:}&  2 &&&&\\
+  \multicolumn{2}{l}{Number of slots:}&         16 &&&&\\
+\\
+  \multicolumn{7}{c}{Offset table} \\
+  \hline
+  slot&  signature&             info&   abbrev&      loc&     line& str\_off \\
+    14& \texttt{0xb5f0ecf455e7e97e}&      325&      452&       84&       52&       72 \\
+    15& \texttt{0x044e413b8a2d1b8f}&        0&        0&        0&        0&        0 \\
+\\
+  \multicolumn{7}{c}{Size table} \\
+  \hline
+  slot&                    &     info&   abbrev&      loc&     line& str\_off \\
+    14&                    &      673&      593&       93&       52&      120 \\
+    15&                    &      325&      452&       84&       52&       72 \\
+\\ \hline 
+\end{tabular}
+\end{center}
+\end{table}
+
+\needlines{4}
+Table \referfol{fig:exampletuindexsection} 
+shows an example TU index section containing the
+three type units for classes \texttt{Box}, \texttt{Point}, and 
+\texttt{Line}. Each type unit
+contains contributions from \dotdebuginfodwo{}, \dotdebugabbrevdwo{},
+\dotdebuglinedwo{} and \dotdebugstroffsetsdwo{}. In this example, the
+type units for classes \texttt{Box} and \texttt{Point} come from 
+\texttt{demo1.dwo}, and
+share the abbreviations table, line number table, and string
+offsets table with the compilation unit from \texttt{demo1.dwo}. 
+Likewise, the type unit for class \texttt{Line} shares tables 
+from \texttt{demo2.dwo}. (The
+sharing of these tables between compilation units and type units
+is typical for some implementations, but is not required by the
+DWARF standard.)
+
+\begin{table}[h]
+\caption{Example TU index section}
+\label{fig:exampletuindexsection}
+\begin{center}
+\begin{tabular}{lrrrrr}
+\hline
+  \multicolumn{2}{l}{Version:}&                 5 \\
+  \multicolumn{2}{l}{Number of columns:}&       4 \\
+  \multicolumn{2}{l}{Number of used entries:}&  3 \\
+  \multicolumn{2}{l}{Number of slots:}&         32 \\
+\\
+  \multicolumn{6}{c}{Offset table} \\
+  \hline
+  slot&  signature&                    info&   abbrev&     line& str\_off \\
+  11& \texttt{0x2f33248f03ff18ab}&     1321&        0&        0&        0 \\
+  17& \texttt{0x79c7ef0eae7375d1}&     1488&      452&       52&       72 \\
+  27& \texttt{0xe97a3917c5a6529b}&      998&        0&        0&        0 \\
+\\
+  \multicolumn{6}{c}{Size table} \\
+  \hline
+  slot&                          &     info&   abbrev&     line& str\_off \\
+  11&                            &     167&      452&       52&       72 \\
+  17&                            &     217&      593&       52&      120 \\
+  27&                            &     323&      452&       52&       72 \\
+\\
+\hline
+\end{tabular}
+\end{center}
+\end{table}
+
+\eb
index afd37b4..192123e 100644 (file)
@@ -843,7 +843,11 @@ a separate \addtoindex{type unit}
 an incomplete declaration 
 \addtoindexx{incomplete type}
 of that type in the compilation unit may provide
-the unique 64-bit signature of the type using a
+the unique 
+\bb
+8-byte 
+\eb
+signature of the type using a
 \addtoindexx{type signature}
 \DWATsignatureDEFN{} attribute.