Merge branch 'HEAD' of dwarfgit@dwarfstd.org:dwarf-doc.git
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
index 356cf63..a227021 100644 (file)
@@ -1,7 +1,8 @@
-\chapter[Split DWARF Objects (Informative)]{Split DWARF Objects (Informative)}
+\chapter[Split DWARF Object Files (Informative)]{Split DWARF Object Files (Informative)}
 \label{app:splitdwarfobjectsinformative}
 \addtoindexx{DWARF compression}
-\addtoindexx{DWARF duplicate elimination}
+\addtoindexx{DWARF duplicate elimination|see{\textit{also} DWARF compression}}
+\addtoindexx{DWARF duplicate elimination|see{\textit{also} split DWARF object file}}
 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
@@ -22,7 +23,12 @@ 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 \refersec{datarep:splitdwarfobjectfiles} describes a
+platform-independent mechanism that allows a producer to
+split the debugging information into relocatable and
+non-relocatable partitions. This Appendix describes the use
+of \splitDWARFobjectfile{s} and provides some illustrative
+examples.
 
 \section{Overview}
 \label{app:splitoverview}
@@ -35,27 +41,26 @@ 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{}) 
-\addtoindexx{\texttt{.dwo} file extension} file.
+\addtoindexx{\texttt{.dwo} file extension} file
+that need not be accessed by the linker.
 
 \needlines{4}
 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 tables used by
-the \dotdebuginfodwo{} sections.
-\item
-\dotdebuglocdwo{} - Contains the location lists referenced by
+\dotdebugloclistsdwo{} - 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 \dotdebugloclists{} section.
 \item
 \dotdebugstrdwo{} - Contains the string table for all indirect
 strings referenced by the debugging information in the
@@ -75,17 +80,22 @@ information entries. Actual line number tables remain in the
 \dotdebugline{} section, and remain in the relocatable object
 (.o) files.
 
-In a .dwo file there is no benefit to having a separate string
+\end{itemize}
+
+In a \texttt{.dwo} file, there is no benefit to having a separate string
 section for directories and file names because the primary
 string table will never be stripped. Accordingly, no
-\texttt{.debug\_line\_str.dwo} is defined. Content descriptions corresponding
-to \DWFORMlinestrp{} in an executable file (for example, in the
-skeleton compilation unit) instead use \DWFORMstrx. This allows
+\texttt{.debug\_line\_str.dwo} section is defined. Content descriptions 
+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).
 
-\end{itemize}
+In a \texttt{.dwo} file, referring to a string using \DWFORMstrp{}
+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
@@ -94,8 +104,7 @@ binary. A skeleton \dotdebuginfo{} section for each compilation unit
 contains a reference to the corresponding \texttt{.o} or \texttt{.dwo}
 file, and the \dotdebugline{} section (which is typically small
 compared to the \dotdebuginfo{} sections) is
-linked into the output binary, as is the new \dotdebugaddr{}
-section.
+linked into the output binary, as is the \dotdebugaddr{} section.
 
 \needlines{6}
 The debug sections that continue to be linked into the
@@ -105,172 +114,158 @@ 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.
+\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 
+skeleton compilation unit DIE, which has 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.
+\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 compilation unit DIE may have the following attributes:
+\par
+\begin{nolinenumbersenv}
 \autocols[0pt]{c}{3}{l}{
 \DWATaddrbase{},
 \DWATcompdir{},
 \DWATdwoname{},
-\DWATdwoid{},
-\DWAThighpc{} \dag,
-\DWATlowpc{} \dag,
-\DWATranges{} \dag,
-\DWATrangesbase{},
+%\DWATdwoid{},
+\DWAThighpc{},
+\DWATlowpc{},
+\DWATranges{},
 \DWATstmtlist{},
 \DWATstroffsetsbase{}
 }
-\dag{} If \DWATranges{} is present, \DWATlowpc{} and \DWAThighpc{} are
-not used, and vice versa.
+\end{nolinenumbersenv}
 
 All other attributes of the compilation unit DIE are moved to
 the full DIE in the \dotdebuginfodwo{} section.
 
-\needlines{4}
-Because of other improvements in \DWARFVersionV, most of the
-relocations that would normally be found in the \dotdebuginfodwo{}
-sections are moved to the \dotdebugaddr{} and
-\dotdebugstroffsetsdwo{} sections. Those in the
-\dotdebugstroffsetsdwo{} sections are simply 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{}
-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}
+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.
 
 \needlines{4}
-Each location list entry contains beginning and ending address
-offsets, which normally may be relocated addresses. In the
-\dotdebuglocdwo{} section, these offsets are replaced by indices
-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
-\addtoindexx{LEB128!unsigned} 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\addtoindexx{LEB128!unsigned} 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 \refersec{chap:normalandpartialcompilationunitentries}). 
-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.
+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 by 
+these strategies:
+
+\begin{enumerate}[1. ]
+\item Some values needing relocation are kept in the \texttt{.o} file
+(for example, references to the line number program from the skeleton
+compilation unit).
+
+\item Some values do not need a relocation because they refer from
+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, referencing a relocatable 
+value in the \dotdebugaddr{} section (which remains in the .o file).
+
+\end{enumerate}
+
+
+Table \refersec{tab:unitattributesbyunitkind} summarizes which
+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}[ht]
+\caption{Unit attributes by unit kind}
+\label{tab:unitattributesbyunitkind}
+\begin{tabular}{P{5.5cm}|cc|ccc}
+\hline
+                        & \multicolumn{5}{c}{\bfseries Unit Kind} \\
+                        & \multicolumn{2}{c}{\bfseries Conventional} 
+                                              & \multicolumn{3}{c}{\bfseries Skeleton and Split} \\
+\bfseries Attribute     & Full \&    &  Type  &  Skeleton & Split Full & Split Type \\
+                        & Partial    &        &           &            &            \\
+\hline
+\DWATaddrbase           & \chkmk  &        &  \chkmk   &        &         \\
+\hline
+\DWATbasetypes          & \chkmk  &        &           &        &         \\
+\hline
+\DWATcompdir            & \chkmk  &        &  \chkmk   &        &         \\
+\hline
+%\DWATdwoid             &         &        &  \chkmk   & \chkmk &         \\
+%\hline
+\DWATdwoname            &         &        &  \chkmk   &        &         \\
+\hline
+\DWATentrypc            & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWAThighpc             & \chkmk  &        &  \chkmk   &        &         \\
+\hline
+\DWATidentifiercase     & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATlanguage           & \chkmk  & \chkmk &           & \chkmk & \chkmk  \\
+\hline
+\DWATloclistsbase       & \chkmk  &        &           &        &         
+\\
+\hline
+\DWATlowpc              & \chkmk  &        &  \chkmk   &        &         \\
+\hline
+\DWATmacros             & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATmainsubprogram     & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATname               & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATproducer           & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATranges             & \chkmk  &        &           & \chkmk &         \\
+\hline
+\DWATrnglistsbase       & \chkmk  &        &           &        &         \\
+\hline
+\DWATstmtlist           & \chkmk  & \chkmk &  \chkmk   &        & \chkmk  \\
+\hline
+\DWATstroffsetsbase     & \chkmk  & \chkmk &  \chkmk   &        &         \\
+\hline
+\DWATuseUTFeight        & \chkmk  & \chkmk &  \chkmk   & \chkmk & \chkmk  \\
+\hline
+\end{tabular}
+\end{table}
 
 \needlines{8}
-This design depends on having an index of debugging information
-available to the consumer. For name lookups, the consumer can use
-the \dotdebugnames{} sections (or an index
-built at link time based on the information in those sections),
-which will lead to a skeleton compilation unit. The
+The split dwarf object file design depends on having an index of 
+debugging information available to the consumer. For name lookups, 
+the consumer can use the \dotdebugnames{} index section (see 
+Section \refersec{chap:acceleratedaccess}) to 
+locate 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
@@ -279,20 +274,30 @@ 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 Example}
-\label{app:splitdwarfobjectexample}
-\addtoindexx{split dwarf object!example}
+\clearpage
+
+\section{Split DWARF Object File Example}
+\label{app:splitdwarfobjectfileexample}
+\addtoindexx{split DWARF object file!example}
 Consider the example source code in 
 Figure \refersec{fig:splitobjectexamplesourcefragment1}, 
 Figure \refersec{fig:splitobjectexamplesourcefragment2} and
 Figure \refersec{fig:splitobjectexamplesourcefragment3}.
-When compiled with split DWARF, we will have two object files,
-\texttt{demo1.o} and \texttt{demo2.o}, and two split DWARF objects
+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]
+In this section, we will use this example to show how the
+connections between the relocatable object file and the split
+DWARF object file are maintained through the linking process. In
+the next section, we will use this same example to show how two
+or more split DWARF object files are combined into a DWARF
+package file.
+
+\vspace{2cm}
+\begin{figure}[ht]
 \textit{File demo1.cc}
-\begin{lstlisting}
+\begin{nlnlisting}
 #include "demo.h"
 
 bool Box::contains(const Point& p) const
@@ -300,14 +305,14 @@ bool Box::contains(const Point& p) const
     return (p.x() >= ll_.x() && p.x() <= ur_.x() &&
             p.y() >= ll_.y() && p.y() <= ur_.y());
 }
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Split object example: source fragment \#1}
 \label{fig:splitobjectexamplesourcefragment1}
 \end{figure}
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \textit{File demo2.cc}
-\begin{lstlisting}
+\begin{nlnlisting}
 #include "demo.h"
 
 bool Line::clip(const Box& b)
@@ -345,14 +350,14 @@ bool Line::clip(const Box& b)
                      b.t());
   }
 }
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Split object example: source fragment \#2}
 \label{fig:splitobjectexamplesourcefragment2}
 \end{figure}
 
-\begin{figure}[h]
+\begin{figure}[ht]
 \textit{File demo.h}
-\begin{lstlisting}
+\begin{nlnlisting}
 class A {
   public:
     Point(float x, float y) : x_(x), y_(y){}
@@ -388,19 +393,18 @@ class Box {
     Point ur_;
 };
 
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Split object example: source fragment \#3}
 \label{fig:splitobjectexamplesourcefragment3}
 \end{figure}
 
 \clearpage
-\subsection{Contents of the Object File}
+\subsection{Contents of the Object Files}
 The object files each contain the following sections of debug
 information:
 \begin{alltt}
   \dotdebugabbrev
   \dotdebuginfo
-  \dotdebugranges
   \dotdebugline
   \dotdebugstr
   \dotdebugaddr
@@ -416,75 +420,47 @@ 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)
+        \DWATstmtlist: (reference to .debug_line section)
       
 \end{alltt}
 \end{dwflisting}
-\caption{Split object example: Skeleton DWARF description}
+\caption{Split object example: skeleton DWARF description}
 \label{fig:splitdwafexampleskeletondwarfdescription}
 \end{figure}
 
 The \DWATcompdir{} and \DWATdwoname{} attributes provide the
-location of the corresponding split DWARF object file that
+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 split DWARF object. This hash serves
+The \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
 two purposes: it can be used to verify that the debug information
-in the split DWARF object matches the information in the object
+in the \splitDWARFobjectfile{} matches the information in the object
 file, and it can be used to find the debug information in a DWARF
 package file.
 
-\needlines{4}
 The \DWATaddrbase{} attribute contains the relocatable offset of
-this object file's contribution to the \dotdebugaddr{} section, and
-the \DWATrangesbase{} attribute contains the relocatable offset
-of this object file's contribution to the \dotdebugranges{} section.
-The \DWATranges{} attribute refers to a specific range list within
-that contribution, and its value is a (non-relocatable) offset
-relative to the base. In a compilation unit with a single
-contiguous range of code, the \DWATranges{} attribute might be
-omitted, and instead replaced by the pair \DWATlowpc{} and
-\DWAThighpc.
+this object file's contribution to the \dotdebugaddr{} section.
 
 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
-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.
-
-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
-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}.
-
+\needlines{6}
 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
@@ -495,8 +471,9 @@ locations in the loadable text and data that are referenced by
 debugging information entries in the split DWARF object. In the
 example in \refersec{fig:splitobjectexamplesourcefragment3}, 
 \texttt{demo1.o} may have three entries:
+\par
+\begin{nolinenumbersenv}
 \begin{center}
-%\footnotesize
 \begin{tabular}{cl}
 Slot & Location referenced \\
 \hline
@@ -505,41 +482,102 @@ Slot & Location referenced \\
    2   &  low PC value for \texttt{Point::y}       \\
 \end{tabular}
 \end{center}
+\end{nolinenumbersenv}
 
 \needlines{4}
 The \dotdebugnames{}
 section contains the names defined by the debugging
-information in the split DWARF object 
-(see Section \refersec{chap:contentsofthenameindex}, 
+information in the \splitDWARFobjectfile{} 
+(see Section \refersec{chap:contentsofthenameindex})
 and references the skeleton compilation unit. 
 When linked together into a final executable,
 they can be used by a DWARF consumer to lookup a name to find one
 or more skeleton compilation units that provide information about
 that name. From the skeleton compilation unit, the consumer can
-find the split DWARF object that it can then read to get the full
+find the \splitDWARFobjectfile{} that it can then read to get the full
 DWARF information.
 
 The \dotdebugaranges{} section contains the PC ranges defined in this
 compilation unit, and allow a DWARF consumer to map a PC value to
-a skeleton compilation unit, and then to a split DWARF object.
+a skeleton compilation unit, and then to a \splitDWARFobjectfile.
+
+
+\subsection{Contents of the Linked Executable File}
+When \texttt{demo1.o} and \texttt{demo2.o} are linked together (along with 
+a main program and other necessary library routines that we will ignore here
+for simplicity), the resulting executable file will contain at least
+the two skeleton compilation units in the \dotdebuginfo{} section, as shown in 
+Figure \referfol{fig:splitobjectexampleexecutablefiledwarfexcerpts}.
 
+\begin{figure}[ht]
+\begin{dwflisting}
+\begin{alltt}
+
+    \DWTAGskeletonunit
+        \DWATcompdir: (reference to directory name in \dotdebugstr)
+        \DWATdwoname: (reference to "demo1.dwo" in \dotdebugstr)
+        \DWATaddrbase: 48 (offset in \dotdebugaddr)
+        \DWATstmtlist: 120 (offset in \dotdebugline)
+    \DWTAGskeletonunit
+        \DWATcompdir: (reference to directory name in \dotdebugstr)
+        \DWATdwoname: (reference to "demo2.dwo" in \dotdebugstr)
+        \DWATaddrbase: 80 (offset in \dotdebugaddr)
+        \DWATstmtlist: 200 (offset in \dotdebugline)
+
+\end{alltt}
+\end{dwflisting}
+\caption{Split object example: executable file DWARF excerpts}
+\label{fig:splitobjectexampleexecutablefiledwarfexcerpts}
+\end{figure}
+
+Each skeleton compilation unit has a \DWATstmtlist{} attribute,
+which provides the relocated offset to that compilation unit's
+contribution in the executable's \dotdebugline{} section. In this
+example, the line number information for \texttt{demo1.dwo} begins at
+offset 120, and for \texttt{demo2.dwo}, it begins at offset 200.
 
-\subsection{Contents of the Split DWARF Object}
-The split DWARF objects each contain the following sections:
+\needlines{4}
+Each skeleton compilation unit also has a \DWATaddrbase{}
+attribute, which provides the relocated offset to that
+compilation unit's contribution in the executable's \dotdebugaddr{}
+section. Unlike the \DWATstmtlist{} attribute, the offset refers
+to the first address table slot, not to the section header. In
+this example, we see that the first address (slot 0) from \texttt{demo1.o}
+begins at offset 48. Because the \dotdebugaddr{} section contains an
+8-byte header, the object file's contribution to the section
+actually begins at offset 40 (for a 64-bit DWARF object, the
+header would be 16 bytes long, and the value for the
+\DWATaddrbase{} attribute would then be 56). All attributes in
+\texttt{demo1.dwo} that use \DWFORMaddrx{} would then refer to address
+table slots relative to that offset. Likewise, the \dotdebugaddr{}
+contribution from \texttt{demo2.dwo} begins at offset 72, and its first
+address slot is at offset 80. Because these contributions have
+been processed by the linker, they contain relocated values for
+the addresses in the program that are referred to by the debug
+information.
+
+The linked executable will also contain \dotdebugabbrev,
+\dotdebugstr{}, \dotdebugnames{} and \dotdebugaranges{} sections, each the
+result of combining and relocating the contributions from the
+relocatable object files.
+
+\needlines{10}
+\subsection{Contents of the Split DWARF Object Files}
+The \splitDWARFobjectfile{s} each contain the following sections:
 \begin{alltt}
   \dotdebugabbrevdwo
   \dotdebuginfodwo{} (for the compilation unit)
   \dotdebuginfodwo{} (one COMDAT section for each type unit)
-  \dotdebuglocdwo
+  \dotdebugloclistsdwo
   \dotdebuglinedwo
   \dotdebugmacrodwo
+  \dotdebugrnglistsdwo
   \dotdebugstroffsetsdwo
   \dotdebugstrdwo
 \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
@@ -551,27 +589,23 @@ 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 split DWARF object file.}
-
 \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
+\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}
@@ -581,39 +615,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}
@@ -629,17 +664,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
@@ -666,16 +701,18 @@ 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}.
 That slot contains the relocated address of the beginning of the
 function.
 
+\needlines{6}
 Each type unit is contained in its own COMDAT \dotdebuginfodwo{}
 section, and looks like a normal type unit in a non-split object,
 except that the \DWTAGtypeunit{} DIE contains a \DWATstmtlist{}
@@ -690,54 +727,39 @@ 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}
-\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. In a split DWARF object file,
-these offsets are not relocatable, since they are not part of the
-relocatable object, but when combined into a DWARF package file,
-each slot must be adjusted to refer to the appropriate offset
-within the merged string table (see Section 
-\refersec{app:dwarfpackagefileexample} for an example of
-a DWARF package file).
+contained in the \dotdebugstrdwo{} section. 
+
+In a split DWARF object file, all references to
+strings go through this table (there are no
+other offsets to \dotdebugstrdwo{} in a split
+DWARF object file). That is, there
+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.
+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. 
+Section \refersec{app:dwarfpackagefileexample} presents
+an example of a DWARF package file.
 
 \needlines{4}
-The \dotdebuglocdwo{} section contains the location lists referenced
+The \dotdebugrnglistsdwo{} section contains range lists referenced by any
+\DWATranges{} attributes in the split DWARF object. In our example,
+\texttt{demo1.o} would have just a single range list for the compilation unit,
+with range list entries for the function \texttt{Box::contains} and for
+out-of-line copies of the inline functions \texttt{Point::x} and \texttt{Point::y}.
+
+The \dotdebugloclistsdwo{} section contains the location lists referenced
 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
-section has a similar format to the \dotdebugloc{} section in a
+section has a similar format to the \dotdebugloclists{} 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}.
+in Section \refersec{datarep:locationlists}. 
 
 \begin{figure}[b]
 \figurepart{1}{2}
@@ -748,24 +770,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}
@@ -778,85 +801,349 @@ 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 4\$ and 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 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.
+location lists at those offsets in the \dotdebugloclistsdwo{} section.
 
-\begin{figure}
+% Special commands for use in the folloing table
+\newcommand{\XXLLEsl}{\hyperlink{chap:DWLLEstartlength}{start\_length}
+                      \index{DW\_LLE\_start\_length}}
+\newcommand{\XXLLEeol}{\hyperlink{chap:DWLLEendoflist}{end\_of\_list}
+                       \index{DW\_LLE\_end\_of\_list}}
+
+\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{center}
+\begin{tabular}{rl|rr|rl}
+   \multicolumn{2}{c}{\textbf{Entry type}}
+                & \multicolumn{2}{c}{\textbf{Range}} 
+                                & \multicolumn{2}{l}{\hspace{6mm}\textbf{Counted Location Description}} \\
+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{center}
 \end{dwflisting}
-\caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebuglocdwo{} excerpts}
-\label{fig:splitobjectexampledemo2dwodwarfdebuglocdwoexcerpts}
+\caption{Split object example: \texttt{demo2.dwo} DWARF \dotdebugloclistsdwo{} excerpts}
+\label{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
 \end{figure}
 
-In each \DWLLEstartlengthentry{}, the start field is the index
-of an slot in the \dotdebugaddr{} section, relative to the base
+In each \DWLLEstartlength{} entry, 
+the start field is the index
+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}
-[TBD]
+
+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
+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
+form \DWFORMstrx{},
+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.
+
+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}). 
+For an executable file named "\texttt{demo}" (or "\texttt{demo.exe}"), a debugger would
+typically expect to find \texttt{demo.dwp} in the same directory as the
+executable file.
+The resulting package file would contain the sections shown in Figure
+\refersec{fig:sectionsandcontributionsinapackagefile}, 
+with contributions from each input file as shown.
+
+\begin{figure}[ht]
+\begin{center}
+\begin{tabular}{P{4.7cm}|P{8cm}}
+\hline
+\bfseries 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
+  \dotdebugrnglistsdwo{} 
+&    \dotdebugrnglistsdwo{} from \texttt{demo1.dwo} \newline
+     \dotdebugrnglistsdwo{} from \texttt{demo2.dwo} \\
+\hline
+  \dotdebugloclistsdwo{}
+&    \dotdebugloclistsdwo{} from \texttt{demo1.dwo} \newline
+     \dotdebugloclistsdwo{} 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{}
+&    merged string table generated by package utility \\
+\hline
+  \dotdebugcuindex
+&    CU index generated by package utility \\
+\hline
+  \dotdebugtuindex
+&    TU index generated by package utility \\
+\hline
+\end{tabular}
+\end{center}
+\caption{Sections and contributions in example package file \texttt{demo.dwp}}
+\label{fig:sectionsandcontributionsinapackagefile}
+\end{figure}
+
+\needlines{4}
+The \dotdebugabbrevdwo{}, \dotdebugrnglistsdwo{}, 
+\dotdebugloclistsdwo{} and \dotdebuglinedwo{}
+sections are copied over from the two \texttt{.dwo} files as
+individual contributions to the corresponding sections in the
+\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 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 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 
+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
+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 \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 \dotdebugloclistsdwo{} begins at offset 84, so the location list from
+Figure \refersec{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts} 
+can be found in \texttt{demo.dwp} at offset 157 (84 + 73) in
+the combined \dotdebugloclistsdwo{} section.
+
+\begin{figure}[ht]
+\begin{center}
+\begin{tabular}{lrrrrrrr}
+\\
+  \multicolumn{7}{c}{Section header} \\
+\hline \\
+  \multicolumn{2}{l}{Version:}&                 5  &&&&&\\
+  \multicolumn{2}{l}{Number of columns:}&       6  &&&&&\\
+  \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&    rng \\ \\
+    14& \texttt{0xb5f0ecf455e7e97e} &      325&      452&       84&       52&       72&    350 \\
+    15& \texttt{0x044e413b8a2d1b8f} &        0&        0&        0&        0&        0&      0 \\
+\\
+  \multicolumn{7}{c}{Size table} \\
+  \hline
+  slot&                    &     info&   abbrev&      loc&     line& str\_off&    rng \\ \\
+    14&                    &      673&      593&       93&       52&      120&     34 \\
+    15&                    &      325&      452&       84&       52&       72&     15 \\
+\\ \hline 
+\end{tabular}
+\end{center}
+\caption{Example CU index section}
+\label{fig:examplecuindexsection}
+\end{figure}
+
+\needlines{4}
+Figure \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{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 \\
+  \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}
+\caption{Example TU index section}
+\label{fig:exampletuindexsection}
+\end{figure}
+