Backup of today's work. Still awaiting a couple more editorial inputs.
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
index 2d1ad95..ecba136 100644 (file)
@@ -42,9 +42,7 @@ 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
-\bb
 that need not be accessed by the linker.
-\eb
 
 \needlines{4}
 The optional set of debugging sections includes the following:
@@ -63,7 +61,6 @@ in the \dotdebuginfo{} section.
 the debugging information entries in the \dotdebuginfodwo{}
 section. This contains the location lists normally found in 
 the \dotdebugloclists{} section.
-\bbeb
 \item
 \dotdebugstrdwo{} - Contains the string table for all indirect
 strings referenced by the debugging information in the
@@ -90,7 +87,11 @@ section for directories and file names because the primary
 string table will never be stripped. Accordingly, no
 \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
+in the skeleton compilation unit) instead use 
+\bb
+one of the forms
+\eb
+\DWFORMstrxXNor. This allows
 directory and file name strings to be merged with general
 strings and across compilations in package files 
 (where they are not subject to potential stripping).
@@ -107,9 +108,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 
-\bbeb
-\dotdebugaddr{} section.
+linked into the output binary, as is the \dotdebugaddr{} section.
 
 \needlines{6}
 The debug sections that continue to be linked into the
@@ -120,9 +119,12 @@ output binary include the following:
 skeleton \dotdebuginfo{} section.
 \item
 \dotdebugaddr{} - Contains references to loadable sections,
-indexed by attributes of form \DWFORMaddrx{} or location
-expression 
-\DWOPaddrx{} opcodes.
+indexed by attributes of 
+\bb
+one of the forms 
+\eb
+\DWFORMaddrxXN{}, 
+or location expression \DWOPaddrx{} opcodes.
 \item
 \dotdebugaranges{} - Contains the accelerated range lookup table
 for the compilation unit.
@@ -130,10 +132,7 @@ for the compilation unit.
 \dotdebugframe{} - Contains the frame tables.
 \item
 \dotdebuginfo{} - Contains a skeleton 
-\bb
-skeleton compilation unit DIE, which has
-\eb
-no children.
+skeleton compilation unit DIE, which has no children.
 \item
 \dotdebugline{} - Contains the line number tables.
 (These could be moved to the .dwo file, but in
@@ -151,21 +150,23 @@ 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.
-\bbeb
+
 \item
 \dotdebugstr{} - Contains any strings referenced by the skeleton
-\dotdebuginfo{} sections (via \DWFORMstrp{} or \DWFORMstrx{}).
+\dotdebuginfo{} sections (via \DWFORMstrp{}, \DWFORMstrxXNor{}).
 \item
 \dotdebugstroffsets{} - Contains the string offsets table for
-the strings in the \dotdebugstr{} section (if form \DWFORMstrx{} is used).
+the strings in the \dotdebugstr{} section (if 
+\bb
+one of the forms
+\eb
+\DWFORMstrxXNor{} is used).
 \end{itemize}
 
 \needlines{6}
-The skeleton 
-\bb
-compilation unit 
-\eb
-DIE may have the following attributes:
+The skeleton compilation unit DIE may have the following attributes:
+\par
+\begin{nolinenumbersenv}
 \autocols[0pt]{c}{3}{l}{
 \DWATaddrbase{},
 \DWATcompdir{},
@@ -174,10 +175,10 @@ DIE may have the following attributes:
 \DWAThighpc{},
 \DWATlowpc{},
 \DWATranges{},
-\bbeb
 \DWATstmtlist{},
 \DWATstroffsetsbase{}
 }
+\end{nolinenumbersenv}
 
 All other attributes of the compilation unit DIE are moved to
 the full DIE in the \dotdebuginfodwo{} section.
@@ -191,10 +192,7 @@ 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 
-\bb
-these
-\eb
-strategies:
+these strategies:
 
 \begin{enumerate}[1. ]
 \item Some values needing relocation are kept in the \texttt{.o} file
@@ -206,10 +204,13 @@ 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 
+program address use 
+\bb
+one of the \DWFORMaddrxXNor{} forms, 
+\eb
+referencing a relocatable 
 value in the \dotdebugaddr{} section (which remains in the .o file).
 
-\bbpareb
 \end{enumerate}
 
 
@@ -248,9 +249,7 @@ kinds.
 \hline
 \DWATlanguage           & \chkmk  & \chkmk &           & \chkmk & \chkmk  \\
 \hline
-\bb
 \DWATloclistsbase       & \chkmk  &        &           &        &         
-\eb
 \\
 \hline
 \DWATlowpc              & \chkmk  &        &  \chkmk   &        &         \\
@@ -263,11 +262,9 @@ kinds.
 \hline
 \DWATproducer           & \chkmk  &        &           & \chkmk &         \\
 \hline
-\bb
-\DWATranges \eb         & \chkmk  &        &           & \chkmk &         \\
+\DWATranges             & \chkmk  &        &           & \chkmk &         \\
 \hline
-\bb
-\DWATrnglistsbase \eb   & \chkmk  &        &           &        &         \\
+\DWATrnglistsbase       & \chkmk  &        &           &        &         \\
 \hline
 \DWATstmtlist           & \chkmk  & \chkmk &  \chkmk   &        & \chkmk  \\
 \hline
@@ -305,19 +302,17 @@ 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}.
 
-\bb
 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.
-\eb
 
 \vspace{2cm}
 \begin{figure}[ht]
 \textit{File demo1.cc}
-\begin{lstlisting}
+\begin{nlnlisting}
 #include "demo.h"
 
 bool Box::contains(const Point& p) const
@@ -325,14 +320,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}[ht]
 \textit{File demo2.cc}
-\begin{lstlisting}
+\begin{nlnlisting}
 #include "demo.h"
 
 bool Line::clip(const Box& b)
@@ -370,14 +365,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}[ht]
 \textit{File demo.h}
-\begin{lstlisting}
+\begin{nlnlisting}
 class A {
   public:
     Point(float x, float y) : x_(x), y_(y){}
@@ -413,15 +408,13 @@ class Box {
     Point ur_;
 };
 
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Split object example: source fragment \#3}
 \label{fig:splitobjectexamplesourcefragment3}
 \end{figure}
 
 \clearpage
-\bb
 \subsection{Contents of the Object Files}
-\eb
 The object files each contain the following sections of debug
 information:
 \begin{alltt}
@@ -453,7 +446,6 @@ Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}.
         \DWATstmtlist: (reference to .debug_line section)
       
 \end{alltt}
-\bbeb
 \end{dwflisting}
 \caption{Split object example: skeleton DWARF description}
 \label{fig:splitdwafexampleskeletondwarfdescription}
@@ -474,13 +466,10 @@ package file.
 
 The \DWATaddrbase{} attribute contains the relocatable offset of
 this object file's contribution to the \dotdebugaddr{} section.
-\bbeb
 
 The \DWATstmtlist{} attribute contains the relocatable offset of
 this file's contribution to the \dotdebugline{} table.
 
-\bbpareb
-
 \needlines{6}
 The \dotdebugline{} section contains the full line number table for
 the compiled code in the object file. As shown in
@@ -497,8 +486,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
@@ -507,6 +497,7 @@ Slot & Location referenced \\
    2   &  low PC value for \texttt{Point::y}       \\
 \end{tabular}
 \end{center}
+\end{nolinenumbersenv}
 
 \needlines{4}
 The \dotdebugnames{}
@@ -526,17 +517,14 @@ compilation unit, and allow a DWARF consumer to map a PC value to
 a skeleton compilation unit, and then to a \splitDWARFobjectfile.
 
 
-\bb
 \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}.
-\eb
 
 \begin{figure}[ht]
-\bb
 \begin{dwflisting}
 \begin{alltt}
 
@@ -555,10 +543,8 @@ Figure \referfol{fig:splitobjectexampleexecutablefiledwarfexcerpts}.
 \end{dwflisting}
 \caption{Split object example: executable file DWARF excerpts}
 \label{fig:splitobjectexampleexecutablefiledwarfexcerpts}
-\eb
 \end{figure}
 
-\bb
 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
@@ -577,7 +563,11 @@ begins at offset 48. Because the \dotdebugaddr{} section contains an
 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
+\texttt{demo1.dwo} that use 
+\bb
+\DWFORMaddrxXNor{} 
+\eb
+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
@@ -589,7 +579,6 @@ 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.
-\eb
 
 \needlines{10}
 \subsection{Contents of the Split DWARF Object Files}
@@ -620,14 +609,15 @@ object file, with the following exceptions:
 compilation unit.
 
 \item References to strings in the string table use the 
-form code \DWFORMstrx, referring to slots in the
+form code \DWFORMstrxXNor, referring to slots in the
 \dotdebugstroffsetsdwo{} section.
 
-\bbpareb
-
 \needlines{4}
-\item References to relocatable addresses in the object file 
-use the form code \DWFORMaddrx, referring to slots in the
+\item References to relocatable addresses in the object file use
+\bb 
+one of the form codes 
+\eb
+\DWFORMaddrxXNor, referring to slots in the
 \dotdebugaddr{} table, relative to the base offset given by
 \DWATaddrbase{} in the skeleton compilation unit.
 \end{itemize}
@@ -739,8 +729,11 @@ Figure~\ref{fig:splitobjectexampledemoonedwodwarfexcerpts}: Split object example
 
 \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}.
+\DWATlowpc{} attribute is represented 
+\bb
+using \DWFORMaddrx, which refers 
+\eb
+to slot 0 in the \dotdebugaddr{} table from \texttt{demo1.o}.
 That slot contains the relocated address of the beginning of the
 function.
 
@@ -781,17 +774,15 @@ Section \refersec{app:dwarfpackagefileexample} presents
 an example of a DWARF package file.
 
 \needlines{4}
-\bb
 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}.
-\eb
 
 The \dotdebugloclistsdwo{} section contains the location lists referenced
 by \DWATlocation{} attributes in the \dotdebuginfodwo{} section. This
-section has a similar format to the \bbeb\dotdebugloclists{} 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:locationlists}. 
 
@@ -904,26 +895,26 @@ offset& (DW\_LLE\_*)
 \hline
 &&&&& \\
 
-0x00 & \XXLLEsl &  [9] & 0x002f & 0x0001 & \DWOPregfive~(rdi) \\
-0x09 & \XXLLEsl & [11] & 0x01b9 & 0x0001 & \DWOPregthree~(rbx) \\
-0x12 & \XXLLEsl & [29] & 0x0003 & 0x0003 & \DWOPbregtwelve~(r12): -8;\\
+0x00 & \XXLLEsl &  [9] & 0x002f & \bb 0x01 \eb& \DWOPregfive~(rdi) \\
+0x09 & \XXLLEsl & [11] & 0x01b9 & \bb 0x01 \eb& \DWOPregthree~(rbx) \\
+0x12 & \XXLLEsl & [29] & 0x0003 & \bb 0x03 \eb& \DWOPbregtwelve~(r12): -8;\\
      &          &      &        &        & \DWOPstackvalue \\
-0x1d & \XXLLEsl & [31] & 0x0001 & 0x0003 & \DWOPentryvalue: \\
+0x1d & \XXLLEsl & [31] & 0x0001 & \bb 0x03 \eb& \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: \\
+0x2a & \XXLLEsl &  [9] & 0x002f & \bb 0x01 \eb& \DWOPregfour~(rsi)) \\
+0x33 & \XXLLEsl & [11] & 0x01ba & \bb 0x03 \eb& \DWOPregsix~(rbp)) \\
+0x3c & \XXLLEsl & [30] & 0x0003 & \bb 0x03 \eb& \DWOPentryvalue: \\
      &          &      &        &        & (\DWOPregfour~(rsi)); \\
      &          &      &        &        & \DWOPstackvalue \\
 0x48 & \XXLLEeol &&&& \\
 ------ &&&&& \\
 
-0x49 & \XXLLEsl & [10] & 0x0004 & 0x0001 & \DWOPregeighteen~(xmm1) \\
-0x52 & \XXLLEsl & [11] & 0x01bd & 0x0002 & \DWOPfbreg: -36 \\
+0x49 & \XXLLEsl & [10] & 0x0004 & \bb 0x01 \eb& \DWOPregeighteen~(xmm1) \\
+0x52 & \XXLLEsl & [11] & 0x01bd & \bb 0x02 \eb& \DWOPfbreg: -36 \\
 0x5c & \XXLLEeol &&&& \\
 &&&& \\
 \end{tabular}
@@ -933,9 +924,7 @@ offset& (DW\_LLE\_*)
 \label{fig:splitobjectexampledemotwodwodwarfdebuglocdwoexcerpts}
 \end{figure}
 
-\bb
 In each \DWLLEstartlength{} entry, 
-\eb
 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{}
@@ -998,8 +987,11 @@ 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}). The
-resulting package file would contain the sections shown in Figure
+(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.
 
@@ -1020,11 +1012,9 @@ with contributions from each input file as shown.
      type unit for class \texttt{Point} from \texttt{demo1.dwo} \newline
      type unit for class \texttt{Line} from \texttt{demo2.dwo}  \\
 \hline
-\bb
   \dotdebugrnglistsdwo{} 
 &    \dotdebugrnglistsdwo{} from \texttt{demo1.dwo} \newline
-     \dotdebugrnglistsdwo{} from \texttt{demo2.dwo}
-\eb  \\
+     \dotdebugrnglistsdwo{} from \texttt{demo2.dwo} \\
 \hline
   \dotdebugloclistsdwo{}
 &    \dotdebugloclistsdwo{} from \texttt{demo1.dwo} \newline
@@ -1054,10 +1044,7 @@ with contributions from each input file as shown.
 \end{figure}
 
 \needlines{4}
-The \dotdebugabbrevdwo{}, 
-\bb
-\dotdebugrnglistsdwo{}, 
-\eb
+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
@@ -1074,6 +1061,7 @@ is also copied. The type units for class \texttt{Box} and class
 and \texttt{demo2.dwo}, but only one instance of each is copied into 
 the package file.
 
+\needlines{4}
 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
@@ -1082,7 +1070,6 @@ 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
@@ -1113,21 +1100,21 @@ the combined \dotdebugloclistsdwo{} section.
   \multicolumn{7}{c}{Section header} \\
 \hline \\
   \multicolumn{2}{l}{Version:}&                 5  &&&&&\\
-  \multicolumn{2}{l}{Number of columns:}&       6\bbeb  &&&&&\\
+  \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
-\bbeb  slot&  signature&                       info&   abbrev&      loc&     line& str\_off&    rng \\
-\bbeb    14& \texttt{0xb5f0ecf455e7e97e} &      325&      452&       84&       52&       72&    350 \\
-\bbeb    15& \texttt{0x044e413b8a2d1b8f} &        0&        0&        0&        0&        0&      0 \\
+  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
-\bbeb  slot&                    &     info&   abbrev&      loc&     line& str\_off&    rng \\
-\bbeb    14&                    &      673&      593&       93&       52&      120&     34 \\
-\bbeb    15&                    &      325&      452&       84&       52&       72&     15 \\
+  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}
@@ -1158,7 +1145,7 @@ DWARF standard.
 \begin{tabular}{lrrrrr}
 \\
   \multicolumn{6}{c}{Section header} \\
-\hline
+\hline \\
   \multicolumn{2}{l}{Version:}&                 5 \\
   \multicolumn{2}{l}{Number of columns:}&       4 \\
   \multicolumn{2}{l}{Number of used entries:}&  3 \\
@@ -1166,14 +1153,14 @@ DWARF standard.
 \\
   \multicolumn{6}{c}{Offset table} \\
   \hline
-  slot&  signature&                    info&   abbrev&     line& str\_off \\
+  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 \\
+  slot&                          &     info&   abbrev&     line& str\_off \\ \\
   11&                            &      167&      452&       52&       72 \\
   17&                            &      217&      593&       52&      120 \\
   27&                            &      323&      452&       52&       72 \\