Working document update--not distributed to Committee/
authorRon Brender <ron.brender@gmail.com>
Sat, 20 Jun 2015 22:23:35 +0000 (18:23 -0400)
committerRon Brender <ron.brender@gmail.com>
Sat, 20 Jun 2015 22:23:35 +0000 (18:23 -0400)
Signed-off-by: Ron Brender <ron.brender@gmail.com>
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/debugsectionrelationships.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/dwarfnamecmds.tex
dwarf5/latexdoc/introduction.tex
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/programscope.tex

index e562c35..f53c4ec 100644 (file)
@@ -15,7 +15,7 @@ This change summary is included only in draft versions of this document.
 \begin{longtable}{ll}
 \textbf{Date}  & \textbf{Issue Incorporated or Other Change}   \\ \hline       \\
 \endhead
-6/14/2015       & More editorial work VII \\
+6/14-20/2015    & More editorial work VII \\
 6/8-13/2015     & More editorial work VI (release to committee) \\
 6/5-7/2015      & Add \definition{color} to defining occurrence(s) of DWARF names.  \\
 5/19-6/4/2015   & More editorial work V \\
index ee085dc..93b3987 100644 (file)
@@ -5,7 +5,6 @@ This section describes the binary representation of the
 debugging information entry itself, of the attribute types
 and of other fundamental elements described above.
 
-
 \section{Vendor Extensibility}
 \label{datarep:vendorextensibility}
 \addtoindexx{vendor extensibility}
@@ -165,6 +164,11 @@ These attributes represent locations
 within the virtual address space of the program, and require
 relocation.
 
+\item A DWARF expression may contain a \DWOPaddr{} (see Section 
+\refersec{chap:literalencodings}) which contains a location within 
+the virtual address space of the program, and require relocation.
+
+\needlines{4}
 \item Debugging information entries may have attributes with the form
 \DWFORMsecoffset{} (see Section \refersec{datarep:attributeencodings}). 
 These attributes refer to
@@ -173,15 +177,7 @@ the object file, and must be relocated during the linking process.
 
 However, if a \DWATrangesbase{} attribute is present, the offset in
 a \DWATranges{} attribute (which uses form \DWFORMsecoffset) is
-relative to the given base offset {no relocation is involved}.
-
-\item Debugging information entries may have attributes with the form
-\DWFORMrefone, \DWFORMreftwo, \DWFORMreffour, \DWFORMrefeight, or
-\DWFORMrefudata{} (see Section \refersec{datarep:attributeencodings}). 
-These attributes refer to other
-debugging information entries within the same compilation unit, and
-are relative to the beginning of the current compilation unit. These
-values do not need relocation.
+relative to the given base offset--no relocation is involved.
 
 \item Debugging information entries may have attributes with the form
 \DWFORMrefaddr{} (see Section \refersec{datarep:attributeencodings}). 
@@ -195,7 +191,8 @@ relocation.
 These attributes refer to strings in
 the \dotdebugstr{} section. These values require relocation.
 
-\item Entries in the \dotdebugloc{}, \dotdebugranges{}, and \dotdebugaranges{}
+\item Entries in the \dotdebugaddr, \dotdebugloc{}, \dotdebugranges{} 
+and \dotdebugaranges{}
 sections contain references to locations within the virtual address
 space of the program, and require relocation.
 
@@ -208,8 +205,27 @@ 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
 emit any explicit relocation information for these offsets).
+
+\item The \HFNdebuginfooffset{} field in the \dotdebugaranges header and 
+the list of compilation units following the \dotdebugnames{} header contain 
+references to the \dotdebuginfo{} section.  These references require relocation 
+so that after linking they refer to the correct contribution in the combined 
+\dotdebuginfo{} section in the executable file.
+
+\item Frame descriptor entries in the \dotdebugframe{} section 
+(see Section \refersec{chap:structureofcallframeinformation}) contain an 
+\HFNinitiallocation{} field value within the virtual address 
+space of the program and require relocation. 
+
 \end{itemize}
 
+\textit{Note that operands of classes \CLASSblock, \CLASSconstant{} and 
+\CLASSflag{} do not require relocation. Attribute operands that use 
+form \DWFORMstring{} also do not require relocation. Further, 
+attribute operands that use form
+\DWFORMrefone, \DWFORMreftwo, \DWFORMreffour, \DWFORMrefeight, or
+\DWFORMrefudata{} do not need relocation.}
+
 \subsection{Split DWARF Object Files}
 \label{datarep:splitdwarfobjectfiles}
 \addtoindexx{split DWARF object file}
@@ -218,6 +234,7 @@ information such that the majority of the debugging
 information can remain in individual object files without
 being processed by the linker. 
 
+\needlines{6}
 \subsubsection{First Partition (with Skeleton Unit)}
 The first partition contains
 debugging information that must still be processed by the linker,
@@ -262,7 +279,7 @@ or DWARF object file that contains the second partition.
 The second partition contains the debugging information that
 does not need to be processed by the linker. These sections
 may be left in the object files and ignored by the linker
-(that is, not combined and copied to the executable object), or
+(that is, not combined and copied to the executable object file), or
 they may be placed by the producer in a separate DWARF object
 file. This partition includes the following:
 \begin{itemize}
@@ -1990,8 +2007,8 @@ beginning of the string offsets information for the
 referencing entity. It is relocatable in
 a relocatable object file, and relocated in an executable or
 shared object file. In the \thirtytwobitdwarfformat, this offset
-is a 4-byte unsigned value; in the 64-bit DWARF
-format, it is an 8-byte unsigned value (see Section
+is a 4-byte unsigned value; in the \sixtyfourbitdwarfformat,
+it is an 8-byte unsigned value (see Section
 \refersec{datarep:32bitand64bitdwarfformats}).
 
 \textit{This class is new in \DWARFVersionV.}
index 72db5ff..0c2e0f7 100644 (file)
@@ -178,10 +178,10 @@ unit entry).
 
 %b
 \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
-The \texttt{debug\_info\_offset} value in the header is the offset in the
+The list of compilation units following the header contains the offsets in the
 \dotdebuginfo{} section of the 
-corresponding compilation unit header (not
-the compilation unit entry). 
+corresponding compilation unit headers (not
+the compilation unit entries). 
 
 %c
 \itembfnl{(c) \dotdebuginfo{} to \dotdebugabbrev}
index 1cac8d9..ca350d3 100644 (file)
@@ -3,7 +3,7 @@
 % If draft is in the document class list, pix are just suggested
 % by an outline, the pic does not appear as a picture.
 %
-\newcommand{\docdate}{June 14, 2015}
+\newcommand{\docdate}{June 20, 2015}
 %
 \usepackage{ifthen}
 \newboolean{isdraft}
index 248a700..9383d57 100644 (file)
 %
 % Header field names
 %
+\newcommand{\HFNaddressrange}             {\addttindex{address\_range}}
 \newcommand{\HFNaddresssize}              {\addttindex{address\_size}}
+\newcommand{\HFNaugmentation}             {\addttindex{augmentation}}
+\newcommand{\HFNCIEid}                    {\addttindex{CIE\_id}}
+\newcommand{\HFNCIEpointer}               {\addttindex{CIE\_pointer}}
+\newcommand{\HFNcodealignmentfactor}      {\addttindex{code\_alignment\_factor}}
+\newcommand{\HFNdataalignmentfactor}      {\addttindex{data\_alignment\_factor}}
 \newcommand{\HFNdebugabbrevoffset}        {\addttindex{debug\_abbrev\_offset}}
 \newcommand{\HFNdebuginfolength}          {\addttindex{debug\_info\_length}}
 \newcommand{\HFNdebuginfooffset}          {\addttindex{debug\_info\_offset}}
 \newcommand{\HFNfilenames}                {\addttindex{file\_names}}
 \newcommand{\HFNflags}                    {\addttindex{flags}}
 \newcommand{\HFNheaderlength}             {\addttindex{header\_length}}
+\newcommand{\HFNinitialinstructions}      {\addttindex{initial\_instructions}}
+\newcommand{\HFNinitiallocation}          {\addttindex{initial\_location}}
+\newcommand{\HFNinstructions}             {\addttindex{instructions}}
+\newcommand{\HFNlength}                   {\addttindex{length}}
 \newcommand{\HFNlinebase}                 {\addttindex{line\_base}}
 \newcommand{\HFNlinerange}                {\addttindex{line\_range}}
 \newcommand{\HFNminimuminstructionlength} {\addttindex{minimum\_instruction\_length}}
 \newcommand{\HFNopcodebase}               {\addttindex{opcode\_base}}
 \newcommand{\HFNopcodeoperandstable}      {\addttindex{opcode\_operands\_table}}
 \newcommand{\HFNopcodeoperandstableflag}  {\addttindex{opcode\_operands\_table\_flag}}
+\newcommand{\HFNpadding}                  {\addttindex{padding}}
+\newcommand{\HFNreturnaddressregister}    {\addttindex{return\_address\_register}}
 \newcommand{\HFNsegmentselectorsize}      {\addttindex{segment\_selector\_size}}
 \newcommand{\HFNstandardopcodelengths}    {\addttindex{standard\_opcode\_lengths}}
 \newcommand{\HFNtypeoffset}               {\addttindex{type\_offset}}
index 60f9a36..aebf862 100644 (file)
@@ -160,7 +160,7 @@ This enhances DWARF support for very large programs by saving space
 and improving link times.
 \item Replace the \dotdebugmacinfo{} macro information representation with
 a much more compact \dotdebugmacro{} representation.
-\item Replace the \dotdebugpubnames{} and \dotdebugtypes{} sections
+\item Replace the \dotdebugpubnames{} and \dotdebugpubtypes{} sections
 with a single and more functional name index section, \dotdebugnames{}.
 \item Add a new debugging information entry (\DWTAGcallsiteNAME) and related 
 attributes and DWARF expression operators to describe call site information, 
index 4cad34c..f2e5be8 100644 (file)
@@ -2098,7 +2098,7 @@ among many Frame Description Entries. There is at least one
 CIE in every non-empty \dotdebugframe{} section. A CIE contains
 the following fields, in order:
 \begin{enumerate}[1. ]
-\item \texttt{length} (\livelink{datarep:initiallengthvalues}{initial length})  \\
+\item \HFNlength{} (\livelink{datarep:initiallengthvalues}{initial length})  \\
 A constant that gives the number of bytes of the CIE structure,
 not including the length field itself 
 (see Section \refersec{datarep:initiallengthvalues}). 
@@ -2106,18 +2106,18 @@ The
 size of the \texttt{length} field plus the value of \texttt{length} must be an
 integral multiple of the address size.
 
-\item  \texttt{CIE\_id} (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
+\item  \HFNCIEid{} (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
 A constant that is used to distinguish CIEs from FDEs.
 
-\item  \texttt{version} (\HFTubyte) \\
+\item  \HFNversion{} (\HFTubyte) \\
 A version number\addtoindexx{version number!call frame information} 
 (see Section \refersec{datarep:callframeinformation}). 
 This number is specific to the call frame information
 and is independent of the DWARF version number.
 
 \needlines{8}
-\item  \texttt{augmentation} (\HFTaugstring) \\
-A null\dash terminated UTF\dash 8 string that identifies the augmentation
+\item  \HFNaugmentation{} (\HFTaugstring) \\
+A null-terminated UTF\dash 8 string that identifies the augmentation
 to this CIE or to the FDEs that use it. If a reader encounters
 an augmentation string that is unexpected, then only the
 following fields can be read:
@@ -2125,9 +2125,9 @@ following fields can be read:
 
 \begin{itemize}
 
-\item CIE: \texttt{length, CIE\_id, version, augmentation}
+\item CIE: \HFNlength, \HFNCIEid, \HFNversion, \HFNaugmentation
 
-\item FDE: \texttt{length, CIE\_pointer, initial\_location, address\_range}
+\item FDE: \HFNlength, \HFNCIEpointer, \HFNinitiallocation, \HFNaddressrange
 
 \end{itemize}
 If there is no augmentation, this value is a zero byte.
@@ -2144,10 +2144,8 @@ any \dotdebuginfo{} section, the augmentation string always uses
 UTF\dash 8 encoding.}
 
 \needlines{4}
-\item  \texttt{address\_size} (\HFTubyte) \\
-The size of a target address
-\addttindexx{address\_size}
-in this CIE and any FDEs that
+\item  \HFNaddresssize{} (\HFTubyte) \\
+The size of a target address in this CIE and any FDEs that
 use it, in bytes. If a compilation unit exists for this frame,
 its address size must match the address size here.
 
@@ -2155,7 +2153,7 @@ its address size must match the address size here.
 The size of a segment selector in this CIE and any FDEs that
 use it, in bytes.
 
-\item  \addttindex{code\_alignment\_factor} (unsigned LEB128) 
+\item  \HFNcodealignmentfactor{} (unsigned LEB128) 
 \addtoindexx{LEB128!unsigned}\addtoindexx{unsigned LEB128|see{LEB128, unsigned}}
 \addtoindexx{code alignment factor} \\
 A 
@@ -2165,23 +2163,23 @@ instructions (see
 Section \refersec{chap:rowcreationinstructions}).
 
 
-\item  \addttindex{data\_alignment\_factor} (signed LEB128)
+\item  \HFNdataalignmentfactor{} (signed LEB128)
 \addtoindexx{LEB128!signed}\addtoindexx{signed LEB128|see{LEB128, signed}} \\
 \addtoindexx{data alignment factor}
 A 
 \addtoindexx{\textless daf\textgreater|see{data alignment factor}}
 constant that is factored out of certain offset instructions
 (see below). The resulting value is  \textit{(operand} *
-\texttt{data\_alignment\_factor}).
+\HFNdataalignmentfactor).
 
-\item  \texttt{return\_address\_register} (unsigned LEB128)\addtoindexx{LEB128!unsigned} \\
+\item  \HFNreturnaddressregister{} (unsigned LEB128)\addtoindexx{LEB128!unsigned} \\
 An unsigned LEB128 constant that indicates which column in the
 rule table represents the return address of the function. Note
 that this column might not correspond to an actual machine
 register.
 
 \needlines{8}
-\item \texttt{initial\_instructions} (array of \HFTubyte) \\
+\item \HFNinitialinstructions{} (array of \HFTubyte) \\
 A sequence of rules that are interpreted to create the initial
 setting of each column in the table.  
 
@@ -2191,7 +2189,7 @@ is the undefined rule. However, an ABI authoring body or a
 compilation system authoring body may specify an alternate
 default value for any or all columns.
 
-\item \texttt{padding} (array of \HFTubyte) \\
+\item \HFNpadding{} (array of \HFTubyte) \\
 Enough \DWCFAnop{} instructions to make the size of this entry
 match the length value above.
 \end{enumerate}
@@ -2199,7 +2197,7 @@ match the length value above.
 \needlines{5}
 An FDE contains the following fields, in order:
 \begin{enumerate}[1. ]
-\item \texttt{length} (\livelink{datarep:initiallengthvalues}{initial length})  \\
+\item \HFNlength{} (\livelink{datarep:initiallengthvalues}{initial length})  \\
 A constant that gives the number of bytes of the header and
 instruction stream for this function, not including the length
 field itself 
@@ -2208,7 +2206,7 @@ The size of the \texttt{length} field
 plus the value of length must be an integral multiple of the
 address size.
 
-\item   CIE\_pointer (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
+\item \HFNCIEpointer{} (4 or 8 bytes, see Section \refersec{datarep:32bitand64bitdwarfformats}) \\
 A constant 
 \addtoindexx{section offset!in FDE header}
 offset into the \dotdebugframe{}
@@ -2216,28 +2214,24 @@ section that denotes
 the CIE that is associated with this FDE.
 
 \needlines{4}
-\item  \texttt{initial\_location} (segment selector and target address) \\
-The 
-\addttindexx{initial\_location}
-address of the first location associated with this table
+\item  \HFNinitiallocation{} (segment selector and target address) \\
+The address of the first location associated with this table
 entry. 
 If the \HFNsegmentselectorsize{} field of this FDE's CIE is non-zero,
 the initial location is preceded by a segment selector of
 the given length.
 
 \needlines{4}
-\item  \texttt{address\_range} (target address) \\
-The 
-\addttindexx{address\_range}
-number 
+\item  \HFNaddressrange{} (target address) \\
+The number 
 \addtoindexx{target address}
 of bytes of program instructions described by this entry.
 
-\item \texttt{instructions} (array of \HFTubyte) \\
+\item \HFNinstructions{} (array of \HFTubyte) \\
 A sequence of table defining instructions that are described below.
 
 \needlines{4}
-\item \texttt{padding} (array of \HFTubyte) \\
+\item \HFNpadding{} (array of \HFTubyte) \\
 Enough \DWCFAnop{} instructions 
 to make the size of this entry match the length value above.
 \end{enumerate}
index 392f827..e7d2cb3 100644 (file)
@@ -526,7 +526,7 @@ and their meanings are given in Table \refersec{tab:languagenames}.
 attribute, whose value is a reference. This attribute points
 to the first string offset of the type unit's contribution to
 the \dotdebugstroffsets{} section. Indirect string references
-(using \DWFORMstrx) within the type unit must be interpreted
+(using \DWFORMstrx) within the type unit are interpreted
 as indices relative to this base.
 
 \item A \DWATstmtlist{} attribute\addtoindexx{statement list attribute}