Incorporate changes as of the May 17 meeting. The corresponding
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
index fe9ff9e..003efcd 100644 (file)
@@ -47,21 +47,20 @@ can be written to a separate DWARF object (.dwo{})
 The optional set of debugging sections includes the following:
 \begin{itemize}
 \item
+\dotdebugabbrevdwo{} - Contains the abbreviations table(s) used by
+the \dotdebuginfodwo{} section.
+\item
 \dotdebuginfodwo{} - Contains the \DWTAGcompileunit{} and
 \DWTAGtypeunit{} DIEs and
 their descendants. This is the bulk of the debugging
 information for the compilation unit that is normally found
 in the \dotdebuginfo{} section.
 \item
-\dotdebugabbrevdwo{} - Contains the abbreviations table(s) used by
-the \dotdebuginfodwo{} section.
-\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.
+the \dotdebugloc{} section, with a 
+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
@@ -90,12 +89,13 @@ string table will never be stripped. Accordingly, no
 corresponding to \DWFORMlinestrp{} in an executable file (for example, 
 in the skeleton compilation unit) instead use \DWFORMstrx. This allows
 directory and file name strings to be merged with general
-strings and across compilations in package files (which are not
-subject to potential stripping).
+strings and across compilations in package files 
+(where they are not subject to potential stripping).
 
 In a \texttt{.dwo} file, referring to a string using \DWFORMstrp{}
-is valid, but such use may complicate incorporation of that file into a
-\texttt{.dwp} file due to changed string offsets as a result of string merging.
+is valid, but such use 
+results in a file that cannot be incorporated into a package file
+(which involves string merging).
 
 In order for the consumer to locate and process the debug
 information, the compiler must produce a small amount of debug
@@ -115,73 +115,74 @@ output binary include the following:
 \dotdebugabbrev{} - Contains the abbreviation codes used by the
 skeleton \dotdebuginfo{} section.
 \item
-\dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
-but no children.
+\dotdebugaddr{} - Contains references to loadable sections,
+indexed by attributes of form \DWFORMaddrx{} or location
+expression 
+\DWOPaddrx{} opcodes.
 \item
-\dotdebugstr{} - Contains any strings referenced by the skeleton
-\dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
+\dotdebugaranges{} - Contains the accelerated range lookup table
+for the compilation unit.
 \item
-\dotdebugstroffsets{} - Contains the string offsets table for
-the strings in the \dotdebugstr{} section (if \DWFORMstrx is used).
+\dotdebugframe{} - Contains the frame tables.
 \item
-\dotdebugaddr{} - Contains references to loadable sections,
-indexed by attributes of form \DWFORMaddrx{} or location
-expression \DWOPaddrx{} opcodes.
+\dotdebuginfo{} - Contains a skeleton \DWTAGcompileunit{} DIE,
+but no children.
 \item
-\dotdebugline{} - Contains the line number tables, unaffected by
-this design. (These could be moved to the .dwo file, but in
+\dotdebugline{} - Contains the line number tables.
+(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.
+\dotdebuglinestr{} - Contains strings for file names used in
+combination with the \dotdebugline{} section.
 \item
 \dotdebugnames{} - Contains the names for use in
-building an index section. This section has the same
-format and use as always. The section header refers to a
+building an index section. 
+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.
+\dotdebugranges{} - Contains the range lists.
+\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 (if form \DWFORMstrx{} is used).
 \end{itemize}
 
 \needlines{6}
-The skeleton \DWTAGcompileunit{} DIE has the following attributes:
+The skeleton \DWTAGcompileunit{} DIE 
+may have the following attributes:
 \autocols[0pt]{c}{3}{l}{
 \DWATaddrbase{},
 \DWATcompdir{},
 \DWATdwoname{},
-\DWATdwoid{},
-\DWAThighpc{} \dag,
-\DWATlowpc{} \dag,
-\DWATranges{} \dag,
+\bbeb %\DWATdwoid{},
+\DWAThighpc{},
+\DWATlowpc{},
+\DWATranges{},
 \DWATrangesbase{},
 \DWATstmtlist{},
 \DWATstroffsetsbase{}
 }
-\dag{} If \DWATranges{} is present, the \DWATlowpc{}/\DWAThighpc{}
-pair is not used, although \DWATlowpc{} may still be present
-to provide a default base address for range list entries.
-Conversely, if the \DWATlowpc/\linebreak[0]\DWAThighpc{} pair is
-present, then \DWATranges{} is not used.
 
 All other attributes of the compilation unit DIE are moved to
 the full DIE in the \dotdebuginfodwo{} section.
-The \DWATdwoid{} attribute is present
-in both the skeleton DIE and the full DIE, so that a consumer
+
+\bb
+The \HFNdwoid{} field is present in headers of the skeleton DIE 
+and the header of the full DIE, so that a consumer
 can verify a match.
+\eb
 
 \needlines{4}
-
-Relocations are neither necessary nor useful in .dwo files, because the
-.dwo files contain only debugging information that does not need to be
+Relocations are neither necessary nor useful in 
+\texttt{.dwo} files, because the \texttt{.dwo}  
+files contain only debugging information that does not need to be
 processed by a linker. Relocations are rendered unnecessary via
 four strategies:
 
@@ -191,9 +192,8 @@ four strategies:
 compilation unit).
 
 \item Some values do not need a relocation because they refer from
-one \dotdwo{} section to another \dotdwo{} section. Because \texttt{.dwo} files are not
-combined by the linker, these references are known at compile time and
-do not need further relocation.
+one \dotdwo{} section to another \dotdwo{} section
+in the same compilation unit. 
 
 \item Some values that need a relocation to refer to a
 relocatable program address use the \DWFORMaddrx{} form,
@@ -209,49 +209,63 @@ skeleton compilation unit in the \texttt{.o} file).
 
 
 Table \refersec{tab:unitattributesbyunitkind} summarizes which
-attributes are defined for use in the various kind of compilation
-units.
+attributes are defined for use in the various 
+kinds of compilation units (see Section \refersec{chap:unitentries}). 
+It compares and contrasts both conventional and split object-related
+kinds.
 
-
-
-\begin{table}[h]
+\begin{table}[ht]
 \caption{Unit attributes by unit kind}
 \label{tab:unitattributesbyunitkind}
-\begin{tabular}{P{5.5cm}|ccccc}
+\begin{tabular}{P{5.5cm}|cc|ccc}
 \hline
                         & \multicolumn{5}{c}{\bfseries Unit Kind} \\
-\bfseries Attribute     &  Full \&   &  Type  &  Skeleton & Split Full & Split Type \\
-                        & Partial    \\
+                        & \multicolumn{2}{c}{\bfseries Conventional} 
+                                              & \multicolumn{3}{c}{\bfseries Skeleton and Split} \\
+\bfseries Attribute     & Full \&    &  Type  &  Skeleton & Split Full & Split Type \\
+                        & Partial    &        &           &            &            \\
 \hline
-\parbox[c]{3cm}{\DWATlowpc, \DWAThighpc, \DWATranges} \parbox[c]{1cm}{\[ \Biggr\} \]}
-                        & \chkmk  &        &  \chkmk   &        &         \\
+\DWATaddrbase           & \chkmk  &        &  \chkmk   &        &         \\
 \hline
-\DWATname               & \chkmk  &        &           & \chkmk &         \\
-\DWATlanguage           & \chkmk  & \chkmk &           & \chkmk & \chkmk  \\
-\DWATstmtlist           & \chkmk  & \chkmk &  \chkmk   &        & \chkmk  \\
+\DWATbasetypes          & \chkmk  &        &           &        &         \\
 \hline
-\DWATmacros             & \chkmk  &        &           & \chkmk &         \\
 \DWATcompdir            & \chkmk  &        &  \chkmk   &        &         \\
-\DWATproducer           & \chkmk  &        &           & \chkmk &         \\
+\hline
+\bbeb %\DWATdwoid       &         &        &  \chkmk   & \chkmk &         \\
+%\hline
+\DWATdwoname            &         &        &  \chkmk   &        &         \\
+\hline
+\DWATentrypc            & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWAThighpc             & \chkmk  &        &  \chkmk   &        &         \\
+\hline
 \DWATidentifiercase     & \chkmk  &        &           & \chkmk &         \\
 \hline
-\DWATbasetypes          & \chkmk  &        &           &        &         \\
-\DWATuseUTFeight        & \chkmk  & \chkmk &  \chkmk   &        & \chkmk  \\
+\DWATlanguage           & \chkmk  & \chkmk &           & \chkmk & \chkmk  \\
+\hline
+\DWATlowpc              & \chkmk  &        &  \chkmk   &        &         \\
+\hline
+\DWATmacros             & \chkmk  &        &           & \chkmk &         \\
+\hline
 \DWATmainsubprogram     & \chkmk  &        &           & \chkmk &         \\
-\DWATentrypc            & \chkmk  &        &           & \chkmk &         \\
 \hline
-\DWATstroffsetsbase     & \chkmk  & \chkmk &  \chkmk   &        &         \\
-\DWATaddrbase           & \chkmk  &        &  \chkmk   &        &         \\
+\DWATname               & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATproducer           & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATranges             & \chkmk  &        &  \chkmk   &        &         \\
+\hline
 \DWATrangesbase         & \chkmk  &        &  \chkmk   &        &         \\
 \hline
-\DWATdwoname            &         &        &  \chkmk   &        &         \\
-\DWATdwoid              &         &        &  \chkmk   & \chkmk &         \\
+\DWATstmtlist           & \chkmk  & \chkmk &  \chkmk   &        & \chkmk  \\
+\hline
+\DWATstroffsetsbase     & \chkmk  & \chkmk &  \chkmk   &        &         \\
+\hline
+\DWATuseUTFeight        & \chkmk  & \chkmk &  \chkmk   & \chkmk & \chkmk  \\
 \hline
 \end{tabular}
 \end{table}
 
-
-
 \needlines{8}
 The split dwarf object file design depends on having an index of 
 debugging information available to the consumer. For name lookups, 
@@ -279,7 +293,8 @@ When compiled with split DWARF, we will have two DWARF object files,
 \texttt{demo1.o} and \texttt{demo2.o}, and two \splitDWARFobjectfile{s}, 
 \texttt{demo1.dwo} and \texttt{demo2.dwo}.
 
-\begin{figure}[b]
+\vspace{2cm}
+\begin{figure}[ht]
 \textit{File demo1.cc}
 \begin{lstlisting}
 #include "demo.h"
@@ -294,7 +309,7 @@ bool Box::contains(const Point& p) const
 \label{fig:splitobjectexamplesourcefragment1}
 \end{figure}
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \textit{File demo2.cc}
 \begin{lstlisting}
 #include "demo.h"
@@ -339,7 +354,7 @@ bool Line::clip(const Box& b)
 \label{fig:splitobjectexamplesourcefragment2}
 \end{figure}
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \textit{File demo.h}
 \begin{lstlisting}
 class A {
@@ -405,19 +420,18 @@ contains just a single DIE, the skeleton compilation unit,
 which may look like 
 Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \begin{dwflisting}
 \begin{alltt}
 
-    \DWTAGcompileunit
-      \DWATcompdir: (reference to directory name in .debug_str)
-      \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
-      \DWATdwoid: 0x44e413b8a2d1b8f
-      \DWATaddrbase: (reference to .debug_addr section)
-      \DWATrangesbase: (reference to range list in .debug_ranges section)
-      \DWATranges: (offset of range list in .debug_ranges section)
-      \DWATstmtlist: (reference to .debug_line section)
-      \DWATlowpc: 0
+    \DWTAGskeletonunit
+        \DWATcompdir: (reference to directory name in .debug_str)
+        \DWATdwoname: (reference to "demo1.dwo" in .debug_str)
+        \DWATaddrbase: (reference to .debug_addr section)
+        \DWATrangesbase: (reference to range list in .debug_ranges section)
+        \DWATranges: (offset of range list in .debug_ranges section)
+        \DWATstmtlist: (reference to .debug_line section)
+        \DWATlowpc: 0
       
 \end{alltt}
 \end{dwflisting}
@@ -430,8 +444,12 @@ location of the corresponding \splitDWARFobjectfile{} that
 contains the full debug information; that file is normally
 expected to be in the same directory as the object file itself.
 
-The \DWATdwoid{} attribute provides a hash of the debug
-information contained in the \splitDWARFobjectfile. This hash serves
+The 
+\bb 
+\HFNdwoid{} field in the header of the skeleton unit provides 
+an ID or key for the debug information contained in the 
+DWARF object file. This ID serves
+\eb
 two purposes: it can be used to verify that the debug information
 in the \splitDWARFobjectfile{} matches the information in the object
 file, and it can be used to find the debug information in a DWARF
@@ -452,28 +470,24 @@ omitted, and instead replaced by the pair \DWATlowpc{} and
 The \DWATstmtlist{} attribute contains the relocatable offset of
 this file's contribution to the \dotdebugline{} table.
 
-If there is a \DWATranges{} attribute, the \DWATlowpc{} attribute
+There is both a \DWATranges{} attribute as well as a \DWATlowpc{} 
+attribute which 
 provides a default base address for the range list entries in the
-\dotdebugranges{} section. It may be omitted if each range list entry
-provides an explicit base address selection entry; it may provide
-a relocatable base address, in which case the offsets in each
-range list entry are relative to it; or it may have the value 0,
-in which case the offsets in each range list entry are themselves
-relocatable addresses.
+\dotdebugranges{} section. 
 
 The \dotdebugranges{} section contains the range list referenced by
 the \DWATranges{} attribute in the skeleton compilation unit DIE,
 plus any range lists referenced by \DWATranges{} attributes in the
-split DWARF object. In our example, \texttt{demo1.o} would contain range
+split DWARF object. In this example, \texttt{demo1.o} contains range
 list entries for the function \texttt{Box::contains}, as well as for
 out-of-line copies of the inline functions \texttt{Point::x} and 
 \texttt{Point::y}.
 
 The \dotdebugline{} section contains the full line number table for
-the compiled code in the object file. In the example in
+the compiled code in the object file. As shown in
 Figure \refersec{fig:splitobjectexamplesourcefragment1}, the line
-number program header would list the two files, \texttt{demo.h} and
-\texttt{demo1.cc}, and would contain line number programs for
+number program header lists the two file names, \texttt{demo.h} and
+\texttt{demo1.cc}, and contains line number programs for
 \texttt{Box::contains}, \texttt{Point::x}, and \texttt{Point::y}.
 
 The \dotdebugstr{} section contains the strings referenced indirectly
@@ -527,8 +541,7 @@ The \splitDWARFobjectfile{s} each contain the following sections:
 \end{alltt}
 The \dotdebugabbrevdwo{} section contains the abbreviation
 declarations for the debugging information entries in the
-\dotdebuginfodwo{} section. In general, it looks just like a normal
-\dotdebugabbrev{} section in a non-split object file.
+\dotdebuginfodwo{} section. 
 
 The \dotdebuginfodwo{} section containing the compilation unit
 contains the full debugging information for the compile unit, and
@@ -540,27 +553,27 @@ object file, with the following exceptions:
 \DWATstmtlist{} attributes that are provided in the skeleton
 compilation unit.
 
-\item References to strings in the string table use the new form
-code \DWFORMstrx, referring to slots in the
+\item References to strings in the string table use the 
+form code \DWFORMstrx, referring to slots in the
 \dotdebugstroffsetsdwo{} section.
 
-\textit{Use of \DWFORMstrp{} is not appropriate in a \splitDWARFobjectfile.}
-
-\needlines{4}
 \item References to range lists in the \dotdebugranges{} section are
 all relative to the base offset given by \DWATrangesbase{}
 in the skeleton compilation unit.
 
-\item References to relocatable addresses in the object file use
-the new form code \DWFORMaddrx, referring to slots in the
+\needlines{4}
+\item References to relocatable addresses in the object file 
+use the form code \DWFORMaddrx, referring to slots in the
 \dotdebugaddr{} table, relative to the base offset given by
 \DWATaddrbase{} in the skeleton compilation unit.
 \end{itemize}
 
-Figure \refersec{fig:splitobjectexampledemo1dwodwarfexcerpts} presents
-some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
+\vspace*{1mm}
+Figure \referfol{fig:splitobjectexampledemoonedwodwarfexcerpts} presents
+excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
 
-\begin{figure}[h]
+\begin{figure}[ht]
+\vspace{1mm}
 \figurepart{1}{2}
 \begin{dwflisting}
 \begin{alltt}
@@ -570,39 +583,40 @@ some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
         \DWATlanguage: \DWLANGCplusplus
         \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc"
         \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name)
-        \DWATdwoid [\DWFORMdataeight]: 0x44e413b8a2d1b8f
-1$:   \DWTAGclasstype
-          \DWATname [\DWFORMstrx]: (slot 12) "Point"
-          \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
-          \DWATdeclaration: true
-2$:     \DWTAGsubprogram
-          \DWATexternal: true
-          \DWATname [\DWFORMstrx]: (slot 12) "Point"
-          \DWATdeclfile: 1
-          \DWATdeclline: 5
-          \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff"
-          \DWATaccessibility: \DWACCESSpublic
-          \DWATdeclaration: true
-        ...
-3$:   \DWTAGclasstype
-          \DWATname [\DWFORMstring]: "Box"
-          \DWATsignature [\DWFORMrefsigeight]: 0xe97a3917c5a6529b
-          \DWATdeclaration: true
-        ...
-4$:     \DWTAGsubprogram
-            \DWATexternal: true
-            \DWATname [\DWFORMstrx]: (slot 0) "contains"
-            \DWATdeclfile: 1
-            \DWATdeclline: 28
-            \DWATlinkagename [\DWFORMstrx]: (slot 8) "_ZNK3Box8containsERK5Point"
-            \DWATtype: (reference to 7$)
-            \DWATaccessibility: \DWACCESSpublic
+1$:     \DWTAGclasstype
+            \DWATname [\DWFORMstrx]: (slot 12) "Point"
+            \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab
             \DWATdeclaration: true
-        ...
+2$:         \DWTAGsubprogram
+                \DWATexternal: true
+                \DWATname [\DWFORMstrx]: (slot 12) "Point"
+                \DWATdeclfile: 1
+                \DWATdeclline: 5
+                \DWATlinkagename [\DWFORMstrx]: (slot 16) "_ZN5PointC4Eff"
+                \DWATaccessibility: \DWACCESSpublic
+                \DWATdeclaration: true
+            ...
+3$:     \DWTAGclasstype
+            \DWATname [\DWFORMstring]: "Box"
+            \DWATsignature [\DWFORMrefsigeight{}]: 0xe97a3917c5a6529b
+            \DWATdeclaration: true
+          ...
+4$:         \DWTAGsubprogram
+                \DWATexternal: true
+                \DWATname [\DWFORMstrx]: (slot 0) "contains"
+                \DWATdeclfile: 1
+                \DWATdeclline: 28
+                \DWATlinkagename [\DWFORMstrx: (slot 8) 
+                                                  "_ZNK3Box8containsERK5Point"
+                \DWATtype: (reference to 7$)
+                \DWATaccessibility: \DWACCESSpublic
+                \DWATdeclaration: true
+          ...
+
 \end{alltt}
 \end{dwflisting}
 \caption{Split object example: \texttt{demo1.dwo} excerpts}
-\label{fig:splitobjectexampledemo1dwodwarfexcerpts}
+\label{fig:splitobjectexampledemoonedwodwarfexcerpts}
 \end{figure}
         
 \begin{figure}
@@ -618,17 +632,17 @@ some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
           \DWAThighpc [\DWFORMdataeight]: 0xbb
           \DWATframebase: \DWOPcallframecfa
           \DWATobjectpointer: (reference to 6$)
-6$:     \DWTAGformalparameter
-            \DWATname [\DWFORMstrx]: (slot 13): "this"
-            \DWATtype: (reference to 8$)
-            \DWATartificial: true
-            \DWATlocation: \DWOPfbreg(-24)
-        \DWTAGformalparameter
-            \DWATname [\DWFORMstring]: "p"
-            \DWATdeclfile: 2
-            \DWATdeclline: 3
-            \DWATtype: (reference to 11$)
-            \DWATlocation: \DWOPfbreg(-32)
+6$:       \DWTAGformalparameter
+              \DWATname [\DWFORMstrx]: (slot 13): "this"
+              \DWATtype: (reference to 8$)
+              \DWATartificial: true
+              \DWATlocation: \DWOPfbreg(-24)
+          \DWTAGformalparameter
+              \DWATname [\DWFORMstring]: "p"
+              \DWATdeclfile: 2
+              \DWATdeclline: 3
+              \DWATtype: (reference to 11$)
+              \DWATlocation: \DWOPfbreg(-32)
       ...
 7$:   \DWTAGbasetype
           \DWATbytesize: 1
@@ -655,10 +669,11 @@ some excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}.
 \end{dwflisting}
 \begin{center}
 \vspace{3mm}
-Figure~\ref{fig:splitobjectexampledemo1dwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
+Figure~\ref{fig:splitobjectexampledemoonedwodwarfexcerpts}: Split object example: \texttt{demo1.dwo} DWARF excerpts \textit{(concluded)}
 \end{center}
 \end{figure}
 
+\needlines{4}
 In the defining declaration for \texttt{Box::contains} at 5\$, the
 \DWATlowpc{} attribute is represented with \DWFORMaddrx,
 referring to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
@@ -679,33 +694,7 @@ reference for filenames needed for \DWATdeclfile{} attributes
 within the type unit.
 
 The \dotdebugstroffsetsdwo{} section contains an entry for each
-unique string in the string table. In the \texttt{demo1.dwo} example,
-these string table slots have been assigned as shown in
-Figure \refersec{fig:splitobjectexamplestringtableslots}.
-
-\begin{figure}[H]
-\begin{center}
-\small
-%\footnotesize
-\begin{tabular}{cl|cl}
-    Slot & String & Slot & String \\
-    \hline
-    0  &   contains                         &    10 &   \_ZNK3Box1rEv \\
-    1  &   \_ZNK5Point1xEv                  &    11 &   \_ZN3BoxC4E5PointS0\_ \\
-    2  &   \_ZNK3Box1lEv                    &    12 &   Point\\
-    3  &   \_ZNK3Box1bEv                    &    13 &   this\\
-    4  &   \textit{(compilation directory)} &    14 &   float \\
-    5  &   bool                             &    15 &   \textit{(producer string)} \\
-    6  &   \_ZN3BoxC4Effff                  &    16 &   \_ZN5PointC4Eff \\
-    7  &   demo1.cc                         &    17 &   \_ZNK3Box1tEv \\
-    8  &   \_ZNK3Box8containsERK5Point      & \\
-    9  &   \_ZNK5Point1yEv                  & \\
-\end{tabular}
-\end{center}
-\caption{Split object example: String table slots}
-\label{fig:splitobjectexamplestringtableslots}
-\end{figure}
-
+unique string in the string table. 
 Each entry in the table is the offset of the string, which is
 contained in the \dotdebugstrdwo{} section. 
 
@@ -718,14 +707,15 @@ is no use of \DWFORMstrp{} in a split DWARF object file.
 The offsets in these slots have no associated relocations, 
 because they are not part of a relocatable object file.
 
+\needlines{4}
 When combined into a DWARF package file, however, each 
 slot must be adjusted to refer to the appropriate offset 
 within the merged string table (\dotdebugstrdwo{}).
 The tool that builds the DWARF package file must understand 
 the structure of the \dotdebugstroffsetsdwo{} section in 
 order to apply the necessary adjustments. 
-(See Section \refersec{app:dwarfpackagefileexample} 
-for an example of a DWARF package file.)
+Section \refersec{app:dwarfpackagefileexample} presents
+an example of a DWARF package file.
 
 \needlines{4}
 The \dotdebuglocdwo{} section contains the location lists referenced
@@ -733,13 +723,6 @@ by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
 section has a similar format to the \dotdebugloc{} section in a
 non-split object, but it has some small differences as explained
 in Section \refersec{datarep:locationlistentriesinsplitobjects}. 
-In \texttt{demo2.dwo} as shown in 
-Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}, 
-the debugging information for \texttt{Line::clip} describes a local 
-variable \texttt{slope} whose location varies based on the PC.
-Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts} 
-presents some excerpts from the \dotdebuginfodwo{} section for 
-\texttt{demo2.dwo}.
 
 \begin{figure}[b]
 \figurepart{1}{2}
@@ -750,24 +733,25 @@ presents some excerpts from the \dotdebuginfodwo{} section for
         \DWATname [\DWFORMstrx]: (slot 20) "Line"
         \DWATsignature [\DWFORMrefsigeight]: 0x79c7ef0eae7375d1
         \DWATdeclaration: true
-    ...
-2$:   \DWTAGsubprogram
-          \DWATexternal: true
-          \DWATname [\DWFORMstrx]: (slot 19) "clip"
-          \DWATdeclfile: 2
-          \DWATdeclline: 16
-          \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
-          \DWATtype: (reference to DIE for bool)
-          \DWATaccessibility: \DWACCESSpublic
-          \DWATdeclaration: true
-      ...
+        ...
+2$:     \DWTAGsubprogram
+            \DWATexternal: true
+            \DWATname [\DWFORMstrx]: (slot 19) "clip"
+            \DWATdeclfile: 2
+            \DWATdeclline: 16
+            \DWATlinkagename [\DWFORMstrx]: (slot 2) "_ZN4Line4clipERK3Box"
+            \DWATtype: (reference to DIE for bool)
+            \DWATaccessibility: \DWACCESSpublic
+            \DWATdeclaration: true
+        ...
+
 \end{alltt}
 \end{dwflisting}
 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts}
-\label{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}
+\label{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts}
 \end{figure}
 
-\begin{figure}
+\begin{figure}[t]
 \figurepart{2}{2}
 \begin{dwflisting}
 \begin{alltt}
@@ -780,73 +764,98 @@ presents some excerpts from the \dotdebuginfodwo{} section for
           \DWAThighpc [\DWFORMdataeight]: 0x1ec
           \DWATframebase: \DWOPcallframecfa
           \DWATobjectpointer: (reference to 4$)
-4$:     \DWTAGformalparameter
-            \DWATname: (indexed string: 0x11): this
-            \DWATtype: (reference to DIE for type const Point* const)
-            \DWATartificial: 1
-            \DWATlocation: 0x0 (location list)
-5$:     \DWTAGformalparameter
-            \DWATname: b
-            \DWATdeclfile: 1
-            \DWATdeclline: 3
-            \DWATtype: (reference to DIE for type const Box& const)
-            \DWATlocation [\DWFORMsecoffset]: 0x2a
-6$:     \DWTAGlexicalblock
-            \DWATlowpc [\DWFORMaddrx]: (slot 17)
-            \DWAThighpc: 0x1d5
-7$:       \DWTAGvariable
-              \DWATname [\DWFORMstrx]: (slot 28): "slope"
+4$:       \DWTAGformalparameter
+              \DWATname: (indexed string: 0x11): this
+              \DWATtype: (reference to DIE for type const Point* const)
+              \DWATartificial: 1
+              \DWATlocation: 0x0 (location list)
+5$:       \DWTAGformalparameter
+              \DWATname: b
               \DWATdeclfile: 1
-              \DWATdeclline: 5
-              \DWATtype: (reference to DIE for type float)
-              \DWATlocation [\DWFORMsecoffset]: 0x49
+              \DWATdeclline: 3
+              \DWATtype: (reference to DIE for type const Box& const)
+              \DWATlocation [\DWFORMsecoffset]: 0x2a
+6$:       \DWTAGlexicalblock
+              \DWATlowpc [\DWFORMaddrx]: (slot 17)
+              \DWAThighpc: 0x1d5
+7$:           \DWTAGvariable
+                  \DWATname [\DWFORMstrx]: (slot 28): "slope"
+                  \DWATdeclfile: 1
+                  \DWATdeclline: 5
+                  \DWATtype: (reference to DIE for type float)
+                  \DWATlocation [\DWFORMsecoffset]: 0x49
 
 \end{alltt}
 \end{dwflisting}
 \begin{center}
 \vspace{3mm}
-Figure~\ref{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
+Figure~\ref{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts}: Split object example: \texttt{demo2.dwo} DWARF \dotdebuginfodwo{} excerpts \textit{(concluded)}
 \end{center}
 \end{figure}
 
-In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuginfodwoexcerpts},
-The \DWTAGformalparameter{} entries at \texttt{4\$} and \texttt{5\$} refer to the
+
+In \texttt{demo2.dwo} as shown in 
+Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts}, 
+the debugging information for \texttt{Line::clip} 
+starting at \texttt{2\$} describes a local 
+variable \texttt{slope} at \texttt{7\$}
+whose location varies based on the PC.
+Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts} 
+presents some excerpts from the \dotdebuginfodwo{} section for 
+\texttt{demo2.dwo}.
+
+\clearpage
+
+In Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuginfodwoexcerpts},
+the \DWTAGformalparameter{} entries at \texttt{4\$} and \texttt{5\$} refer to the
 location lists at offset \texttt{0x0} and \texttt{0x2a}, respectively, and the
-\DWTAGvariable{} entry for \texttt{slope} at \texttt{7\$} refers to the location
-list at offset \texttt{0x49}. 
-Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
+\DWTAGvariable{} entry for \texttt{slope} 
+refers to the location list at offset \texttt{0x49}. 
+Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
 shows a representation of the
 location lists at those offsets in the \dotdebuglocdwo{} section.
 
-\begin{figure}
+% Special commands for use in the folloing table
+\newcommand{\XXLLEsl}{\hyperlink{chap:DWLLEstartlengthentry}{start\_length\_entry}
+                      \index{DW\_LLE\_start\_length\_entry}}
+\newcommand{\XXLLEeol}{\hyperlink{chap:DWLLEendoflistentry}{end\_of\_list\_entry}
+                       \index{DW\_LLE\_end\_of\_list\_entry}}
+
+\begin{figure}[ht]
 \begin{dwflisting}
-\begin{tabular}{rlrrl}
-\texttt{offset} & entry type & start & length & expression \\
-\hline \\
-0x00 & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfive~(rdi) \\
-0x09 & \DWLLEstartlengthentry & [11] & 0x01b9 & \DWOPregthree~(rbx) \\
-0x12 & \DWLLEstartlengthentry & [29] & 0x0003 & \DWOPbregtwelve~(r12):\\
-&&&& -8; \DWOPstackvalue \\
-0x1d & \DWLLEstartlengthentry & [31] & 0x0001 & \DWOPentryvalue: \\
-&&&& (\DWOPregfive~(rdi)); \\
-&&&& \DWOPstackvalue \\
-0x29 & \DWLLEendoflistentry &&& \\
-\\   & \hhline{-} &&& \\
-0x2a & \DWLLEstartlengthentry &  [9] & 0x002f & \DWOPregfour~(rsi)) \\
-0x33 & \DWLLEstartlengthentry & [11] & 0x01ba & \DWOPregsix~(rbp)) \\
-0x3c & \DWLLEstartlengthentry & [30] & 0x0003 & \DWOPentryvalue: \\
-&&&& (\DWOPregfour~(rsi)); \\
-&&&& \DWOPstackvalue \\
-0x48 & \DWLLEendoflistentry &&& \\
-\\   & \hhline{-} &&& \\
-0x49 & \DWLLEstartlengthentry & [10] & 0x0004 & \DWOPregeighteen~(xmm1) \\
-0x52 & \DWLLEstartlengthentry & [11] & 0x01bd & \DWOPfbreg: -36 \\
-0x5c & \DWLLEendoflistentry &&& \\
+\begin{tabular}{rl|rr|rl}
+       &  entry type          & \multicolumn{2}{c}{range} 
+                                               & \multicolumn{2}{l}{\hspace{6mm}location} \\
+offset & (DW\_LLE\_*)         & start & length & length & expression \\
+\hline
+&&&&& \\
+
+0x00 & \XXLLEsl &  [9] & 0x002f & 0x0001 & \DWOPregfive~(rdi) \\
+0x09 & \XXLLEsl & [11] & 0x01b9 & 0x0001 & \DWOPregthree~(rbx) \\
+0x12 & \XXLLEsl & [29] & 0x0003 & 0x0003 & \DWOPbregtwelve~(r12): -8;\\
+     &          &      &        &        & \DWOPstackvalue \\
+0x1d & \XXLLEsl & [31] & 0x0001 & 0x0003 & \DWOPentryvalue: \\
+     &          &      &        &        & (\DWOPregfive~(rdi)); \\
+     &          &      &        &        & \DWOPstackvalue \\
+0x29 & \XXLLEeol &&&& \\
+------ &&&&& \\
+
+0x2a & \XXLLEsl &  [9] & 0x002f & 0x0001 & \DWOPregfour~(rsi)) \\
+0x33 & \XXLLEsl & [11] & 0x01ba & 0x0003 & \DWOPregsix~(rbp)) \\
+0x3c & \XXLLEsl & [30] & 0x0003 & 0x0003 & \DWOPentryvalue: \\
+     &          &      &        &        & (\DWOPregfour~(rsi)); \\
+     &          &      &        &        & \DWOPstackvalue \\
+0x48 & \XXLLEeol &&&& \\
+------ &&&&& \\
+
+0x49 & \XXLLEsl & [10] & 0x0004 & 0x0001 & \DWOPregeighteen~(xmm1) \\
+0x52 & \XXLLEsl & [11] & 0x01bd & 0x0002 & \DWOPfbreg: -36 \\
+0x5c & \XXLLEeol &&&& \\
 &&&& \\
 \end{tabular}
 \end{dwflisting}
 \caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
-\label{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
+\label{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
 \end{figure}
 
 In each \DWLLEstartlengthentry{}, the start field is the index
@@ -854,17 +863,19 @@ of a slot in the \dotdebugaddr{} section, relative to the base
 offset defined by the compilations unit's \DWATaddrbase{}
 attribute. The \dotdebugaddr{} slots referenced by these entries give
 the relocated address of a label within the function where the
-address range begins. The length field gives the length of the
-address range.
+address range begins. 
+The following length field gives the length of the
+address range. The location, consisting of its own length and
+a DWARF expression, is last.
 
 \clearpage
 \section{DWARF Package File Example}
 \label{app:dwarfpackagefileexample}
 \addtoindexx{DWARF duplicate elimination!examples}
 
-\bb
-A \definitionx{DWARF package file} is a collection of split 
-DWARF object files.
+A \addtoindex{DWARF package file} 
+(see Section \refersec{datarep:dwarfpackagefiles}) 
+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
@@ -889,8 +900,9 @@ 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 table. Because all references to these strings use
+form \DWFORMstrx{},
+the packaging utility only needs to adjust the
 string offsets in each \dotdebugstroffsetsdwo{} contribution after
 building the new \dotdebugstrdwo{} section.
 
@@ -906,20 +918,18 @@ 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
+For 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 Figure
 \refersec{fig:sectionsandcontributionsinapackagefile}, 
 with contributions from each input file as shown.
-\eb
 
-\begin{figure}[h]
-\bb
+\begin{figure}[ht]
 \begin{center}
 \begin{tabular}{P{4.7cm}|P{8cm}}
 \hline
-\bfseries Target \texttt{.dwp} section & \bfseries Source of section contributions \\
+\bfseries Section & \bfseries Source of section contributions \\
 \hline
   \dotdebugabbrevdwo{}
 &    \dotdebugabbrevdwo{} from \texttt{demo1.dwo} \newline
@@ -945,46 +955,46 @@ with contributions from each input file as shown.
      \dotdebugstroffsetsdwo{} from \texttt{demo2.dwo}, \hspace*{6mm}adjusted \\
 \hline
   \dotdebugstrdwo{}
-&    new merged string table \\
+&    merged string table generated by package utility \\
 \hline
   \dotdebugcuindex
-&    new CU index \\
+&    CU index generated by package utility \\
 \hline
   \dotdebugtuindex
-&    new TU index \\
+&    TU index generated by package utility \\
 \hline
 \end{tabular}
 \end{center}
-\caption{Sections and contributions in a package file}
+\caption{Sections and contributions in example package file \texttt{demo.dwp}}
 \label{fig:sectionsandcontributionsinapackagefile}
-\eb
 \end{figure}
 
 \needlines{4}
-\bb
 The \dotdebugabbrevdwo{}, \dotdebuglocdwo{} and \dotdebuglinedwo{}
-sections have been copied over from the two \texttt{.dwo} files as
+sections are 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
+\texttt{.dwp} file. 
+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 
+The \dotdebuginfodwo{} sections corresponding to each compilation 
+unit are copied as individual contributions to the combined
+\dotdebuginfodwo{} section, and one copy of each type unit 
+is also 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
+The \dotdebugstrdwo{} sections from each file are 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
+\dotdebugstroffsetsdwo{} sections from the \texttt{.dwo} files 
+are copied as individual contributions, but the string table offset
+in each slot of those contributions is adjusted to point to
 the correct offset in the merged string table.
 
+\needlines{4}
 The \dotdebugcuindex{} and \dotdebugtuindex{} sections provide a
 directory to these contributions. 
 Figure \referfol{fig:examplecuindexsection} shows an example CU
@@ -998,21 +1008,21 @@ unit from \texttt{demo2.dwo}, with \CUsignature{}
 section begins at offset 325, and is 673 bytes long.
 
 Likewise, we can find the contributions to the related sections.
-In Figure \refersec{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}, 
+In Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}, 
 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 {fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts} 
+Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts} 
 can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
 the combined \dotdebuglocdwo{} section.
-\eb
 
-\begin{figure}[h]
-\bb
+\begin{figure}[ht]
 \begin{center}
 \begin{tabular}{lrrrrrr}
+\\
+  \multicolumn{7}{c}{Section header} \\
 \hline \\
   \multicolumn{2}{l}{Version:}&                 5 &&&&\\
   \multicolumn{2}{l}{Number of columns:}&       5 &&&&\\
@@ -1035,11 +1045,9 @@ the combined \dotdebuglocdwo{} section.
 \end{center}
 \caption{Example CU index section}
 \label{fig:examplecuindexsection}
-\eb
 \end{figure}
 
 \needlines{4}
-\bb
 Figure \referfol{fig:exampletuindexsection} 
 shows an example TU index section containing the
 three type units for classes \texttt{Box}, \texttt{Point}, and 
@@ -1051,16 +1059,17 @@ type units for classes \texttt{Box} and \texttt{Point} come from
 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
+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.)
-\eb
+DWARF standard.
 
-\begin{figure}[h]
-\bb
+\begin{figure}[ht]
 \begin{center}
 \begin{tabular}{lrrrrr}
+\\
+  \multicolumn{6}{c}{Section header} \\
 \hline
   \multicolumn{2}{l}{Version:}&                 5 \\
   \multicolumn{2}{l}{Number of columns:}&       4 \\
@@ -1077,15 +1086,14 @@ DWARF standard.)
   \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 \\
+  11&                            &      167&      452&       52&       72 \\
+  17&                            &      217&      593&       52&      120 \\
+  27&                            &      323&      452&       52&       72 \\
 \\
 \hline
 \end{tabular}
 \end{center}
 \caption{Example TU index section}
 \label{fig:exampletuindexsection}
-\eb
 \end{figure}