Update/backup current working version. Not for general committee release.
[dwarf-doc.git] / dwarf5 / latexdoc / datarepresentation.tex
index 58087e7..832bf60 100644 (file)
@@ -64,20 +64,20 @@ other vendors.
 
 To ensure that extensions added by one vendor may be safely
 ignored by consumers that do not understand those extensions,
-the following rules should be followed:
+the following rules must be followed:
 \begin{enumerate}[1. ]
 
-\item New attributes should be added in such a way that a
+\item New attributes are added in such a way that a
 debugger may recognize the format of a new attribute value
 without knowing the content of that attribute value.
 
-\item The semantics of any new attributes should not alter
+\item The semantics of any new attributes do not alter
 the semantics of previously existing attributes.
 
-\item The semantics of any new tags should not conflict with
+\item The semantics of any new tags do not conflict with
 the semantics of previously existing tags.
 
-\item Do not add any new forms of attribute value.
+\item New forms of attribute value are not added.
 
 \end{enumerate}
 
@@ -95,8 +95,8 @@ a convenience for consumers of DWARF information, the value
 forms, base type encodings, location operations, languages,
 line number program opcodes, macro information entries and tag
 names to represent an error condition or unknown value. DWARF
-does not specify names for these reserved values, since they
-do not represent valid encodings for the given type and should
+does not specify names for these reserved values, because they
+do not represent valid encodings for the given type and do
 not appear in DWARF debugging information.
 
 
@@ -201,7 +201,7 @@ space of the program, and require relocation.
 opcode is a reference to a location within the virtual address space
 of the program, and requires relocation.
 
- The \dotdebugstroffsets{} section contains a list of string offsets,
+\item The \dotdebugstroffsets{} section contains a list of string offsets,
 each of which is an offset of a string in the \dotdebugstr{} section. Each
 of these offsets requires relocation. Depending on the implementation,
 these relocations may be implicit (that is, the producer may not need to
@@ -297,6 +297,10 @@ to a debugging information section (for example, \dotdebuginfo),
 applies also to the corresponding split DWARF section (for example,
 \dotdebuginfodwo).
 
+Split DWARF object files do not get linked with any other files,
+therefore references between sections must not make use of
+normal object file relocation information. 
+
 \subsection{Executable Objects}
 \label{chap:executableobjects}
 The relocated addresses in the debugging information for an
@@ -333,7 +337,7 @@ extension.\addtoindexx{\texttt{.dwp} file extension}}
 A DWARF package file is itself an object file, using the
 \addtoindexx{package files}
 \addtoindexx{DWARF package files}
-same object file format (including byte order) as the
+same object file format (including \byteorder) 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.
@@ -375,7 +379,7 @@ 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
+Each \compunitset{} may contain contributions from the
 following sections:
 \begin{alltt}
     \dotdebuginfodwo{} (required)
@@ -386,7 +390,7 @@ following sections:
     \dotdebugmacrodwo
 \end{alltt}
 
-\textit{Note that a set is not able to represent \dotdebugmacinfo{}
+\textit{Note that a \compunitset{} is not able to represent \dotdebugmacinfo{}
 information from \DWARFVersionIV{} or earlier formats.}
 
 \subsubsection{The Type Unit (TU) Index Section}
@@ -395,7 +399,7 @@ 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
+Each \typeunitset{} may contain contributions from the following
 sections:
 \begin{alltt}
     \dotdebuginfodwo{} (required) 
@@ -407,10 +411,10 @@ sections:
 \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
+Each index 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.
+boundaries in the DWARF package file.
 
 \needlines{6}
 The index section header contains the following fields:
@@ -448,13 +452,13 @@ The size of the hash table, $S$, must be $2^k$ such that:
 \hspace{0.3cm}$2^k\ \ >\ \ 3*U/2$
 
 The hash table begins at offset 16 in the section, and consists
-of an array of $S$ 64-bit slots. Each slot contains a 64-bit
+of an array of $S$ 8-byte slots. Each slot contains a 64-bit
 signature.
-% (using the byte order of the application binary).
+% (using the \byteorder{} of the application binary).
 
 The parallel table of indices begins immediately after the hash table 
 (at offset \mbox{$16 + 8 * S$} from the beginning of the section), and
-consists of an array of $S$ 32-bit slots,
+consists of an array of $S$ 4-byte 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
@@ -486,7 +490,7 @@ 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 * S$} from the beginning of the section).
-The table is a two-dimensional array of 32-bit words, 
+The table is a two-dimensional array of 4-byte words, 
 %(using the byte order of the application binary), 
 with $C$ columns and $U + 1$
 rows, in row-major order. Each row in the array is indexed
@@ -522,23 +526,23 @@ Table \referfol{tab:dwarfpackagefilesectionidentifierencodings}.
 \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
+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
+contains a \HFNdebugabbrevoffset{} 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
+\dotdebugabbrevdwo{} section for that CU or TU, and are
 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
+\DWATstmtlist{} attributes are interpreted as relative to
 the base offset for \dotdebuglinedwo{}, and offsets into other debug
-sections obtained from DWARF attributes should also be
+sections obtained from DWARF attributes are also 
 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
+the table of offsets, it is a two-dimensional array of 4-byte
 words, with $C$ columns and $U$ 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).
@@ -555,7 +559,7 @@ from the debugging information of each of those executable or shared object file
 \needlines{4}
 A DWARF \addtoindex{supplementary object file} is itself an object file, 
 using the same object
-file format, byte order, and size as the corresponding application executables
+file format, \byteorder{}, and size as the corresponding application executables
 or shared libraries. It consists only of a file header, section table, and
 a number of DWARF debug information sections.  Both the 
 \addtoindex{supplementary object file}
@@ -615,18 +619,19 @@ to import entries from the \addtoindex{supplementary object file}, other \DWFORM
 attributes to refer to them and \DWFORMstrpsup{} form attributes to
 refer to strings that are used by debug information of multiple
 executables or shared object files.  Within the \addtoindex{supplementary object file}'s
-debugging sections, form \DWFORMrefsup{} or \DWFORMstrpsup{} should
-not be used, and all reference forms referring to some other sections
+debugging sections, form \DWFORMrefsup{} or \DWFORMstrpsup{} are
+not used, and all reference forms referring to some other sections
 refer to the local sections in the \addtoindex{supplementary object file}.
 
-In macro information, \DWMACROdefineindirectsup{} or
-\DWMACROundefindirectsup{} opcodes can refer to strings in the 
+In macro information, \DWMACROdefinesup{} or
+\DWMACROundefsup{} opcodes can refer to strings in the 
 \dotdebugstr{} section of the \addtoindex{supplementary object file}, 
-or \DWMACROtransparentincludesup{} 
+or \DWMACROimportsup{} 
 can refer to \dotdebugmacro{} section entries.  Within the 
 \dotdebugmacro{} section of a \addtoindex{supplementary object file}, 
-\DWMACROdefineindirect{} and \DWMACROundefindirect{}
-opcodes refer to the local \dotdebugstr{} section, not the one in
+\DWMACROdefinestrp{} and \DWMACROundefstrp{}
+opcodes refer to the local \dotdebugstr{} section in that
+supplementary file, not the one in
 the executable or shared object file.
 
 
@@ -639,10 +644,10 @@ the executable or shared object file.
 There are two closely related file formats. In the 32-bit DWARF
 format, all values that represent lengths of DWARF sections
 and offsets relative to the beginning of DWARF sections are
-represented using 32-bits. In the 64-bit DWARF format, all
+represented using four bytes. In the 64-bit DWARF format, all
 values that represent lengths of DWARF sections and offsets
 relative to the beginning of DWARF sections are represented
-using 64-bits. A special convention applies to the initial
+using eight bytes. A special convention applies to the initial
 length field of certain DWARF sections, as well as the CIE and
 FDE structures, so that the 32-bit and 64-bit DWARF formats
 can coexist and be distinguished within a single linked object.
@@ -655,15 +660,15 @@ detailed in the following:
 \addtoindex{initial length} field (see 
 \addtoindexx{initial length!encoding}
 Section \ref{datarep:initiallengthvalues} on page \pageref{datarep:initiallengthvalues})
-is an unsigned 32-bit integer (which
+is an unsigned 4-byte integer (which
 must be less than \xfffffffzero); in the 64-bit DWARF format,
-an \addtoindex{initial length} field is 96 bits in size,
+an \addtoindex{initial length} field is 12 bytes in size,
 and has two parts:
 \begin{itemize}
-\item The first 32-bits have the value \xffffffff.
+\item The first four bytes have the value \xffffffff.
 
-\item  The following 64-bits contain the actual length
-represented as an unsigned 64-bit integer.
+\item  The following eight bytes contain the actual length
+represented as an unsigned 8-byte integer.
 \end{itemize}
 
 \textit{This representation allows a DWARF consumer to dynamically
@@ -679,8 +684,8 @@ fields that occur
 in the headers of DWARF sections (other than initial length
 \addtoindexx{initial length}
 fields) are listed following. In the 32-bit DWARF format these
-are 32-bit unsigned integer values; in the 64-bit DWARF format,
-they are 64-bit unsigned integer values.
+are 4-byte unsigned integer values; in the 64-bit DWARF format,
+they are 8-byte unsigned integer values.
 
 \begin{center}
 \begin{tabular}{lll}
@@ -705,8 +710,8 @@ each other (both offset and size).
 \item Within the body of the \dotdebuginfo{}
 section, certain forms of attribute value depend on the choice
 of DWARF format as follows. For the 32-bit DWARF format,
-the value is a 32-bit unsigned integer; for the 64-bit DWARF
-format, the value is a 64-bit unsigned integer.
+the value is a 4-byte unsigned integer; for the 64-bit DWARF
+format, the value is an 8-byte unsigned integer.
 \begin{center}
 \begin{tabular}{lp{6cm}}
 Form             & Role  \\ \hline
@@ -725,8 +730,8 @@ Form             & Role  \\ \hline
 \needlines{5}
 \item Within the body of the \dotdebugline{} section, certain forms of content
 description depend on the choice of DWARF format as follows: for the
-32-bit DWARF format, the value is a 32-bit unsigned integer; for the
-64-bit DWARF format, the value is a 64-bit unsigned integer.
+32-bit DWARF format, the value is a 4-byte unsigned integer; for the
+64-bit DWARF format, the value is a 8-byte unsigned integer.
 \begin{center}
 \begin{tabular}{lp{6cm}}
 Form             & Role  \\ \hline
@@ -740,15 +745,15 @@ compilation units (CUs) and the array of local type units
 (TUs), which represents an offset in the 
 \dotdebuginfo{}
 section, depends on the DWARF format as follows: in the
-32-bit DWARF format, each entry is a 32-bit unsigned integer;
-in the 64-bit DWARF format, it is a 64-bit unsigned integer.
+32-bit DWARF format, each entry is a 4-byte unsigned integer;
+in the 64-bit DWARF format, it is a 8-byte unsigned integer.
 
 \needlines{4}
 \item In the body of the \dotdebugstroffsets{} and \dotdebugstroffsetsdwo{}
 sections, the size of entries in the body depend on the DWARF
-format as follows: in the 32-bit DWARF format, entries are 32-bit
+format as follows: in the 32-bit DWARF format, entries are 4-byte
 unsigned integer values; in the 64-bit DWARF format, they are
-64-bit unsigned integers.
+8-byte unsigned integers.
 
 \item In the body of the \dotdebugaddr{}, \dotdebugloc{} and \dotdebugranges{}
 sections, the contents of the address size fields depends on the
@@ -890,8 +895,7 @@ The value of this field is
 \textit{This field is new in \DWARFVersionV.}
 
 \needlines{4}
-\item \addttindex{debug\_abbrev\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
-\addttindexx{debug\_abbrev\_offset}
+\item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
 A 
 \addtoindexx{section offset!in .debug\_info header}
 4-byte or 8-byte unsigned offset into the 
@@ -953,8 +957,7 @@ The value of this field is \DWUTtype{} for a type unit
 \textit{This field is new in \DWARFVersionV.}
 
 \needlines{4}
-\item \addttindex{debug\_abbrev\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
-\addttindexx{debug\_abbrev\_offset}
+\item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\
 A 
 \addtoindexx{section offset!in .debug\_info header}
 4-byte or 8-byte unsigned offset into the 
@@ -979,7 +982,7 @@ offset portion of an address.
 \item \texttt{type\_signature} (8-byte unsigned integer) \\
 \addttindexx{type\_signature}
 \addtoindexx{type signature}
-A 64-bit unique signature (see Section 
+A unique 64-bit signature (see Section 
 \refersec{datarep:typesignaturecomputation})
 of the type described in this type
 unit.  
@@ -1471,7 +1474,7 @@ Table \referfol{tab:attributeencodings}.
         \livelink{chap:classexprloc}{exprloc}
             \addtoindexx{rank attribute}  \\
 \DWATstroffsetsbase~\ddag&0x72&
-               \livelinki{chap:classstring}{stroffsetsptr}{stroffsetsptr class}
+               \livelinki{chap:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class}
             \addtoindexx{string offsets base!encoding} \\
 \DWATaddrbase~\ddag &0x73&
                \livelinki{chap:classaddrptr}{addrptr}{addrptr class}
@@ -1557,9 +1560,22 @@ the list of classes allowed by the applicable attribute in
 Table \refersec{tab:attributeencodings}
 determines the class of the form.
 
+In the form descriptions that follow, some forms are said
+to depend in part on the value of an attribute of the
+\definition{\associatedcompilationunit}:
+\begin{itemize}
+\item
+In the case of a \splitDWARFobjectfile{}, the associated
+compilation unit is the skeleton compilation unit corresponding 
+to the containing unit.
+\item Otherwise, the associated compilation unit 
+is the containing unit.
+\end{itemize}
 
 \needlines{4}
-Each possible form belongs to one or more of the following classes:
+Each possible form belongs to one or more of the following classes
+(see Table \refersec{tab:classesofattributevalue} for a summary of
+the purpose and general usage of each class):
 
 \begin{itemize}
 \item \livelinki{chap:classaddress}{address}{address class} \\
@@ -1582,6 +1598,7 @@ The representation of a \DWFORMaddrxNAME{} value is an unsigned
 index into an array of addresses in the \dotdebugaddr{} section.
 The index is relative to the value of the \DWATaddrbase{} attribute 
 of the associated compilation unit.
+
 \end{itemize}
 
 \needlines{5}
@@ -1659,7 +1676,7 @@ be a signed integer, an unsigned integer, a floating\dash point
 constant, or anything else. A consumer must use context to
 know how to interpret the bits, which if they are target
 machine data (such as an integer or floating-point constant)
-will be in target machine byte\dash order.
+will be in target machine \byteorder.
 
 \textit{If one of the \DWFORMdataTARG\textless n\textgreater 
 forms is used to represent a
@@ -2032,7 +2049,7 @@ small in magnitude.
 
 \textit{This encoding is equally suitable whether the target machine
 architecture represents data in big\dash\ endian or little\dash endian
-order. It is \doublequote{little\dash endian} only in the sense that it
+\byteorder. It is \doublequote{little\dash endian} only in the sense that it
 avoids using space to represent the \doublequote{big} end of an
 unsigned integer, when the big end is all zeroes or sign
 extension bits.}
@@ -2059,12 +2076,12 @@ numbers. The
 that an additional byte follows.
 
 
-The encoding for signed, two\textquoteright s complement LEB128 
+The encoding for signed, two\textquoteright{s} complement LEB128 
 (\addtoindex{SLEB128}) \addtoindexx{LEB128!signed, encoding as}
 numbers is similar, except that the criterion for discarding
 high order bytes is not whether they are zero, but whether
 they consist entirely of sign extension bits. Consider the
-32-bit integer -2. The three high level bytes of the number
+4-byte integer -2. The three high level bytes of the number
 are sign extension, thus LEB128 would represent it as a single
 byte containing the low order 7 bits, with the high order
 bit cleared to indicate the end of the byte stream. Note
@@ -2337,11 +2354,9 @@ Table \refersec{tab:locationlistentryencodingvalues}.
 
 The encodings of the 
 \hypertarget{chap:DWATencodingencodingofbasetype}{}
-constants used in 
-\addtoindexx{encoding attribute}
-the 
-\DWATencoding{}
-attribute are given in 
+constants used in the 
+\DWATencodingDEFN{} attribute\addtoindexx{encoding attribute} 
+are given in 
 Table \refersec{tab:basetypeencodingvalues}
 
 \begin{centering}
@@ -2807,16 +2822,16 @@ The number of unique names in the index.
 The size in bytes of the abbreviations table.
 
 \item \texttt{augmentation\_string\_size} (\HFTuword) \\
-The size in bytes of the augmentation string. This value should be
+The size in bytes of the augmentation string. This value is 
 rounded up to a multiple of 4.
 
 \item \texttt{augmentation\_string} (\HFTaugstring) \\
 A vendor-specific augmentation string, which provides additional 
 information about the contents of this index. If provided, the string
-should begin with a 4-character vendor ID. The remainder of the
+begins with a 4-character vendor ID. The remainder of the
 string is meant to be read by a cooperating consumer, and its
 contents and interpretation are not specified here. The
-string should be padded with null characters to a multiple of
+string is padded with null characters to a multiple of
 four bytes in length.
 
 \end{enumerate}
@@ -3084,20 +3099,20 @@ Table \refersec{tab:macroinfoentrytypeencodings}.
   \hline \ddag~\textit{New in DWARF Version 5}
 \endlastfoot
 
-\DWMACROdefine~\ddag              &0x01 \\
-\DWMACROundef~\ddag               &0x02 \\
-\DWMACROstartfile~\ddag           &0x03 \\
-\DWMACROendfile~\ddag             &0x04 \\
-\DWMACROdefineindirect~\ddag      &0x05 \\
-\DWMACROundefindirect~\ddag       &0x06 \\
-\DWMACROtransparentinclude~\ddag  &0x07 \\
-\DWMACROdefineindirectsup~\ddag   &0x08 \\
-\DWMACROundefindirectsup~\ddag    &0x09 \\
-\DWMACROtransparentincludesup~\ddag&0x0a \\
-\DWMACROdefineindirectx~\ddag     &0x0b \\
-\DWMACROundefindirectx~\ddag      &0x0c \\
-\DWMACROlouser~\ddag              &0xe0 \\
-\DWMACROhiuser~\ddag              &\xff \\
+\DWMACROdefine~\ddag          &0x01 \\
+\DWMACROundef~\ddag           &0x02 \\
+\DWMACROstartfile~\ddag       &0x03 \\
+\DWMACROendfile~\ddag         &0x04 \\
+\DWMACROdefinestrp~\ddag      &0x05 \\
+\DWMACROundefstrp~\ddag       &0x06 \\
+\DWMACROimport~\ddag          &0x07 \\
+\DWMACROdefinesup~\ddag       &0x08 \\
+\DWMACROundefsup~\ddag        &0x09 \\
+\DWMACROimportsup~\ddag       &0x0a \\
+\DWMACROdefinestrx~\ddag      &0x0b \\
+\DWMACROundefstrx~\ddag       &0x0c \\
+\DWMACROlouser~\ddag          &0xe0 \\
+\DWMACROhiuser~\ddag          &\xff \\
 
 \end{longtable}
 \end{centering}
@@ -3540,8 +3555,8 @@ code, and the attribute value.
 \DWATdiscrlist,
 \DWATdiscrvalue,
 \DWATencoding,
-\DWATenumclass,
 \DWATendianity,
+\DWATenumclass,
 \DWATexplicit,
 \DWATisoptional,
 \DWATlocation,
@@ -3579,7 +3594,7 @@ spelling of their identifier.
 
 If an implementation defines any vendor-specific attributes,
 any such attributes that are essential to the definition of
-the type should also be included at the end of the above list,
+the type are also included at the end of the above list,
 in their own alphabetical suborder.
 
 An attribute that refers to another type entry T is processed
@@ -3667,22 +3682,22 @@ using the values defined earlier in this chapter.
 Appendix \refersec{app:typesignaturecomputationgrammar}.
 }
 
-\textit{An attribute that refers to another type entry should
-be recursively processed or replaced with the name of the
+\textit{An attribute that refers to another type entry is
+recursively processed or replaced with the name of the
 referent (in Step 4, 5 or 6). If neither treatment applies to
 an attribute that references another type entry, the entry
-that contains that attribute should not be considered for a
+that contains that attribute is not suitable for a
 separate \addtoindex{type unit}.}
 
 \textit{If a debugging information entry contains an attribute from
 the list above that would require an unsupported form, that
-entry should not be considered for a separate 
+entry is not suitable for a separate 
 \addtoindex{type unit}.}
 
-\textit{A type should be considered for a separate 
+\textit{A type is suitable for a separate 
 \addtoindex{type unit} only
 if all of the type entries that it contains or refers to in
-Steps 6 and 7 can themselves each be considered for a separate
+Steps 6 and 7 are themselves suitable for a separate
 \addtoindex{type unit}.}
 
 \needlines{4}
@@ -3701,7 +3716,7 @@ the type that uniquely identifies that type (that is, a different
 type is highly unlikely to produce the same string).}
 
 \needlines{6}
-\textit{A debugging information entry should not be placed in a
+\textit{A debugging information entry is not be placed in a
 separate \addtoindex{type unit}
 if any of the following apply:}
 
@@ -3775,7 +3790,7 @@ access name index table (see Section \refersec{chap:acceleratedaccess})
 is defined in \addtoindex{C} as shown in 
 Figure \referfol{fig:nametablehashfunctiondefinition}.\footnote{
 This hash function is sometimes informally known as the 
-"\addtoindex{TJB hash function}" or the "\addtoindex{Berstein hash function}"
+"\addtoindex{DJB hash function}" or the "\addtoindex{Berstein hash function}"
 (see, for example, 
 \hrefself{http://en.wikipedia.org/wiki/List\_of\_hash\_functions} or
 \hrefself{http://stackoverflow.com/questions/10696223/reason-for-5381-number-in-djb-hash-function)}.}