Posted a review document this date. Includes all issues and
[dwarf-doc.git] / dwarf5 / latexdoc / datarepresentation.tex
index 5a5d8d4..ea74431 100644 (file)
@@ -128,7 +128,7 @@ the other values is reserved for possible future extensions.
 
 
 
-\section{Relocatable, Split, Executable and Shared Objects} 
+\section{Relocatable, Split, Executable, Shared and Package Object Files} 
 \label{datarep:executableobjectsandsharedobjects}
 
 \subsection{Relocatable Objects}
@@ -237,6 +237,208 @@ shared object may be calculated by adding the offset to the
 base address at which the object was attached. This offset
 is available in the run\dash time linker\textquoteright s data structures.}
 
+\subsection{DWARF Package Files}
+\label{datarep:dwarfpackagefiles}
+\textit{Using split DWARF objects allows the developer to compile, 
+link, and debug an application quickly with less link-time overhead,
+but a more convenient format is needed for saving the debug
+information for later debugging of a deployed application. A
+DWARF package file can be used to collect the debugging
+information from the object (or separate DWARF object) files
+produced during the compilation of an application.}
+
+\textit{The package file is typically placed in the same directory as the
+application, and is given the same name with a \doublequote{\texttt{.dwp}}
+extension.\addtoindexx{\texttt{.dap} file extension}}
+
+A DWARF package file is itself an object file, using the
+\addtoindexx{package files}
+\addtoindexx{DWARF package files}
+same object file format, byte order, and size as the
+corresponding application binary. It consists only of a file
+header, section table, a number of DWARF debug information
+sections, and two index sections.
+
+Each DWARF package file contains no more than one of each of the
+following sections, copied from a set of object or DWARF object
+files, and combined, section by section:
+\begin{alltt}
+    \dotdebuginfodwo
+    \dotdebugabbrevdwo
+    \dotdebuglinedwo
+    \dotdebuglocdwo
+    \dotdebugstroffsetsdwo
+    \dotdebugstrdwo
+    \dotdebugmacrodwo
+\end{alltt}
+
+The string table section in \dotdebugstrdwo{} contains all the
+strings referenced from DWARF attributes using the form
+\DWFORMstrx. Any attribute in a compilation unit or a type
+unit using this form will refer to an entry in that unit's
+contribution to the \dotdebugstroffsetsdwo{} section, which in turn
+will provide the offset of a string in the \dotdebugstrdwo{}
+section.
+
+The DWARF package file also contains two index sections that
+provide a fast way to locate debug information by compilation
+unit signature (\DWATdwoid) for compilation units, or by type
+signature for type units:
+\begin{alltt}
+    \dotdebugcuindex
+    \dotdebugtuindex
+\end{alltt}
+
+\subsubsection{The Compilation Unit (CU) Index Section}
+The \dotdebugcuindex{} section is a hashed lookup table that maps a
+compilation unit signature to a set of contributions in the
+various debug information sections. Each contribution is stored
+as an offset within its corresponding section and a size.
+
+Each compilation unit set may contain contributions from the
+following sections:
+\begin{alltt}
+    \dotdebuginfodwo{} (required)
+    \dotdebugabbrevdwo{} (required)
+    \dotdebuglinedwo
+    \dotdebuglocdwo
+    \dotdebugstroffsetsdwo
+    \dotdebugmacrodwo
+\end{alltt}
+
+\textit{Note that a set is not able to represent \dotdebugmacinfo{}
+information from \DWARFVersionIV{} or earlier formats.}
+
+\subsubsection{The Type Unit (TU) Index Section}
+The \dotdebugtuindex{} section is a hashed lookup table that maps a
+type signature to a set of offsets into the various debug
+information sections. Each contribution is stored as an offset
+within its corresponding section and a size.
+
+Each type unit set may contain contributions from the following
+sections:
+\begin{alltt}
+    \dotdebuginfodwo{} (required) 
+    \dotdebugabbrevdwo{} (required)
+    \dotdebuglinedwo
+    \dotdebugstroffsetsdwo
+\end{alltt}
+
+\subsubsection{Format of the CU and TU Index Sections}
+Both index sections have the same format, and serve to map a
+64-bit signature to a set of contributions to the debug sections.
+Each section begins with a header, followed by a hash table of
+signatures, a parallel table of indexes, a table of offsets, and
+a table of sizes. The index sections are aligned at 8-byte
+boundaries in the file.
+
+\needlines{6}
+The index section header contains four unsigned 32-bit values
+(using the byte order of the application binary):
+\begin{itemize}
+\item The \addtoindexi{version number}{version number!package index tables}
+ of the format of this index (currently 5)
+\item L, the number of columns in the table of section offsets
+\item N, the number of compilation units or type units in the index
+\item M, the number of slots in the hash table
+\end{itemize}
+
+\textit{We assume that N and M will not exceed $2^{32}$.}
+
+The size of the hash table, M, must be $2^k$ such that:
+\hspace{0.3cm}$2^k\ \ >\ \ 3*N/2$
+
+The hash table begins at offset 16 in the section, and consists
+of an array of M 64-bit slots. Each slot contains a 64-bit
+signature (using the byte order of the application binary).
+
+The parallel table begins immediately after the hash table (at
+offset \mbox{16 + 8 * M} from the beginning of the section), and
+consists of an array of M 32-bit slots (using the byte order of
+the application binary), corresponding 1-1 with slots in the hash
+table. Each entry in the parallel table contains a row index into
+the tables of offsets and sizes.
+
+Unused slots in the hash table have 0 in both the hash table
+entry and the parallel table entry. While 0 is a valid hash
+value, the row index in a used slot will always be non-zero.
+
+Given a 64-bit compilation unit signature or a type signature S,
+an entry in the hash table is located as follows:
+\begin{enumerate}[1. ]
+\item Calculate a primary hash $H = S\ \&\ MASK(k)$, where $MASK(k)$ is a
+    mask with the low-order k bits all set to 1.
+
+\item Calculate a secondary hash $H' = (((S>>32)\ \&\ MASK(k))\ |\ 1)$.
+
+\item If the hash table entry at index H matches the signature, use
+    that entry. If the hash table entry at index H is unused (all
+    zeroes), terminate the search: the signature is not present
+    in the table.
+
+\item Let $H = (H + H')\ modulo\ M$. Repeat at Step 3.
+\end{enumerate}
+
+Because $M > N$, and H' and M are relatively prime, the search is
+guaranteed to stop at an unused slot or find the match.
+
+\needlines{4}
+The table of offsets begins immediately following the parallel
+table (at offset \mbox{16 + 12 * M} from the beginning of the section).
+The table is a two-dimensional array of 32-bit words (using the
+byte order of the application binary), with L columns and N+1
+rows, in row-major order. Each row in the array is indexed
+starting from 0. The first row provides a key to the columns:
+each column in this row provides an identifier for a debug
+section, and the offsets in the same column of subsequent rows
+refer to that section. The section identifiers are shown in
+Table \referfol{tab:dwarfpackagefilesectionidentifierencodings}.
+
+\begin{centering}
+\setlength{\extrarowheight}{0.1cm}
+\begin{longtable}{l|c|l}
+  \caption{DWARF package file section identifier \mbox{encodings}}
+  \label{tab:dwarfpackagefilesectionidentifierencodings}
+  \addtoindexx{DWARF package files!section identifier encodings} \\
+  \hline \bfseries Section identifier &\bfseries Value &\bfseries Section \\ \hline
+\endfirsthead
+  \bfseries Section identifier &\bfseries Value &\bfseries Section\\ \hline
+\endhead
+  \hline \emph{Continued on next page}
+\endfoot
+  \hline
+\endlastfoot
+\DWSECTINFOTARG         & 1 & \dotdebuginfodwo \\
+\textit(reserved)       & 2 & \\
+\DWSECTABBREVTARG       & 3 & \dotdebugabbrevdwo \\
+\DWSECTLINETARG         & 4 & \dotdebuglinedwo \\
+\DWSECTLOCTARG          & 5 & \dotdebuglocdwo \\
+\DWSECTSTROFFSETSTARG   & 6 & \dotdebugstroffsetsdwo \\
+%DWSECTMACINFO          &   & \dotdebugmacinfodwo \\
+\DWSECTMACROTARG        & 7 & \dotdebugmacrodwo \\
+\end{longtable}
+\end{centering}
+
+The offsets provided by the CU and TU index sections are the base
+offsets for the contributions made by each CU or TU to the
+corresponding section in the package file. Each CU and TU header
+contains an \texttt{abbrev\_offset} field, used to find the abbreviations
+table for that CU or TU within the contribution to the
+\dotdebugabbrevdwo{} section for that CU or TU, and should be
+interpreted as relative to the base offset given in the index
+section. Likewise, offsets into \dotdebuglinedwo{} from
+\DWATstmtlist{} attributes should be interpreted as relative to
+the base offset for \dotdebuglinedwo{}, and offsets into other debug
+sections obtained from DWARF attributes should also be
+interpreted as relative to the corresponding base offset.
+
+The table of sizes begins immediately following the table of
+offsets, and provides the sizes of the contributions made by each
+CU or TU to the corresponding section in the package file. Like
+the table of offsets, it is a two-dimensional array of 32-bit
+words, with L columns and N rows, in row-major order. Each row in
+the array is indexed starting from 1 (row 0 of the table of
+offsets also serves as the key for the table of sizes).
 
 \needlines{6}
 \section{32-Bit and 64-Bit DWARF Formats}
@@ -264,7 +466,7 @@ detailed in the following:
 \addtoindex{initial length field}
 (see 
 \addtoindexx{initial length field!encoding}
-Section \refersec{datarep:initiallengthvalues}) 
+Section \ref{datarep:initiallengthvalues} on page \pageref{datarep:initiallengthvalues})
 is an unsigned 32\dash bit integer (which
 must be less than \xfffffffzero); in the 64\dash bit DWARF format,
 an \addtoindex{initial length field} is 96 bits in size,
@@ -1488,14 +1690,14 @@ Table \refersec{tab:attributeformencodings}.
 \DWATmacros~\ddag &0x79&\livelink{chap:classmacptr}{macptr} 
         \addtoindexx{macro information attribute!encoding}  \\
 \DWATcallallcalls~\ddag &0x7a&\CLASSflag
-        \addtoindexx{all calls summary attribute!encoding}\\
+        \addtoindexx{all calls summary attribute!encoding} \\
 \DWATcallallsourcecalls~\ddag &0x7b &\CLASSflag
         \addtoindexx{all source calls summary attribute!encoding} \\
 \DWATcallalltailcalls~\ddag &0x7c&\CLASSflag
         \addtoindexx{all tail calls summary attribute!encoding} \\
-\DWATcalldatalocation~\ddag &0x7d&\CLASSexprloc
+\DWATcalldatalocation~\ddag &0x7d &\CLASSexprloc
         \addtoindexx{call data location attribute!encoding} \\
-\DWATcalldatavalue~\ddag &0x7e&\CLASSexprloc
+\DWATcalldatavalue~\ddag &0x7e &\CLASSexprloc
         \addtoindexx{call data value attribute!encoding} \\
 \DWATcallorigin~\ddag &0x7f &\CLASSexprloc
         \addtoindexx{call origin attribute!encoding} \\
@@ -2132,6 +2334,8 @@ defined language.
 \DWLANGOCaml{} \ddag &0x001b &0        \addtoindexx{OCaml}\\
 \DWLANGRust{} \ddag &0x001c &0 \addtoindexx{Rust}\\
 \DWLANGCeleven{} \ddag &0x001d &0 \addtoindexx{C:2011 (ISO)}\\
+\DWLANGSwift{} \ddag &0x001e &0 \addtoindexx{Swift} \\
+\DWLANGJulia{} \ddag &0x001f &1 \addtoindexx{Julia} \\
 \DWLANGlouser{} &0x8000 & \\
 \DWLANGhiuser{} &\xffff & \\
 
@@ -2694,6 +2898,7 @@ DWARF format, this consists of the 4-byte value
 that gives the actual length (see 
 Section \refersec{datarep:32bitand64bitdwarfformats}).
 
+\needlines{4}
 \item  \texttt{version} (\addtoindex{uhalf}) \\
 A 2-byte version identifier containing the value
 \versiondotdebugstroffsets{} 
@@ -2959,6 +3164,7 @@ the type definitions that are contained in
 \addtoindexx{type unit}
 type units.
 
+\needlines{4}
 The type signature for a type T0 is formed from the 
 \MDfive{}\footnote{\livetarg{def:MDfive}{MD5} Message Digest Algorithm, 
 R.L. Rivest, RFC 1321, April 1992}
@@ -3087,6 +3293,7 @@ to the following:
 \DWFORMexprloc,
 and \DWFORMblock.
 
+\needlines{4}
 \item If the tag in Step 3 is one of \DWTAGpointertype,
 \DWTAGreferencetype, 
 \DWTAGrvaluereferencetype,
@@ -3238,6 +3445,7 @@ information entry are encoded by name rather than by recursively
 encoding the type to allow for cases where a complete definition 
 of the type might not be available in all compilation units.}
 
+\needlines{4}
 \textit{If a type definition contains the definition of a member function, 
 it cannot be moved as is into a type unit, because the member function 
 contains attributes that are unique to that compilation unit.