Backup of today's work. Still awaiting a couple more editorial inputs.
[dwarf-doc.git] / dwarf5 / latexdoc / splitobjects.tex
index 7294d49..ecba136 100644 (file)
@@ -87,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).
@@ -115,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.
@@ -146,14 +153,20 @@ skeleton compilation unit in the \dotdebuginfo{} section.
 
 \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 compilation unit DIE may have the following attributes:
+\par
+\begin{nolinenumbersenv}
 \autocols[0pt]{c}{3}{l}{
 \DWATaddrbase{},
 \DWATcompdir{},
@@ -165,6 +178,7 @@ The skeleton compilation unit DIE may have the following attributes:
 \DWATstmtlist{},
 \DWATstroffsetsbase{}
 }
+\end{nolinenumbersenv}
 
 All other attributes of the compilation unit DIE are moved to
 the full DIE in the \dotdebuginfodwo{} section.
@@ -190,7 +204,11 @@ 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).
 
 \end{enumerate}
@@ -294,7 +312,7 @@ 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
@@ -302,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)
@@ -347,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){}
@@ -390,7 +408,7 @@ class Box {
     Point ur_;
 };
 
-\end{lstlisting}
+\end{nlnlisting}
 \caption{Split object example: source fragment \#3}
 \label{fig:splitobjectexamplesourcefragment3}
 \end{figure}
@@ -468,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
@@ -478,6 +497,7 @@ Slot & Location referenced \\
    2   &  low PC value for \texttt{Point::y}       \\
 \end{tabular}
 \end{center}
+\end{nolinenumbersenv}
 
 \needlines{4}
 The \dotdebugnames{}
@@ -543,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
@@ -585,12 +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.
 
 \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}
@@ -702,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.
 
@@ -865,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}
@@ -1031,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
@@ -1039,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
@@ -1076,13 +1106,13 @@ the combined \dotdebugloclistsdwo{} section.
 \\
   \multicolumn{7}{c}{Offset table} \\
   \hline
-  slot&  signature&                       info&   abbrev&      loc&     line& str\_off&    rng \\
+  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 \\
+  slot&                    &     info&   abbrev&      loc&     line& str\_off&    rng \\ \\
     14&                    &      673&      593&       93&       52&      120&     34 \\
     15&                    &      325&      452&       84&       52&       72&     15 \\
 \\ \hline 
@@ -1115,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 \\
@@ -1123,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 \\