Version for committee consideration at complete\ion of public review.
authorRon Brender <ron.brender@gmail.com>
Sat, 26 Nov 2016 16:19:41 +0000 (11:19 -0500)
committerRon Brender <ron.brender@gmail.com>
Sat, 26 Nov 2016 16:19:41 +0000 (11:19 -0500)
Signed-off-by: Ron Brender <ron.brender@gmail.com>
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/examples.tex
dwarf5/latexdoc/foreword.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/splitobjects.tex

index ca70d90..bc94567 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
-10/10-11/20/2016& Miscellaneous editorial tweaks during public review \\
+10/10-11/26/2016& Miscellaneous editorial tweaks during public review \\
 10/6/2016       & Prepare Public Review Draft, delete bullet 7 in 7.4, other tweaks. \\
 9/13/2016       & Final edits for committee vote \\
 9/4/2016        & Further Appendix F cleanups \\
index 959fb75..188dac1 100644 (file)
@@ -3,14 +3,14 @@
 % 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}{November 20, 2016}
+\newcommand{\docdate}{November 26, 2016}
 %
 \usepackage{ifthen}
     \newcommand{\ifthen}[2]{\ifthenelse{#1}{#2}{}}
     \newboolean{isdraft}\setboolean{isdraft}{true}
     \newboolean{uselinenumbers}\setboolean{uselinenumbers}{true}
     \newboolean{usechangesummary}\setboolean{usechangesummary}{false}
-\newcommand{\draftmark}{\ifthenelse{\boolean{isdraft}}{*** PRE-PUBLIC RELEASE DRAFT ***}{}}
+\newcommand{\draftmark}{\ifthenelse{\boolean{isdraft}}{*** PRE-APPROVED STANDARD DRAFT ***}{}}
 %
 \usepackage[T1]{fontenc}
 \usepackage{palatino}
index 03c8946..99370c5 100644 (file)
@@ -270,6 +270,8 @@ Following are examples of DWARF operations used to form location descriptions:
 
 \newcommand{\descriptionitemnl}[1]
         {\vspace{0.3\baselineskip}\item[#1]\mbox{}\\\vspace{0.5\baselineskip}}
+
+
 \begin{description}
 \descriptionitemnl{\DWOPregthree}
 The value is in register 3.
@@ -305,8 +307,9 @@ A variable whose first four bytes reside in register 3 and whose next
 two bytes reside in register 10.
 
 \needlines{4}
-\descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4}
-\vspace{-2\parsep}A twelve byte value whose first four bytes reside in register zero,
+\descriptionitemnl{\DWOPregzero{} \DWOPpiece{} 4 \DWOPpiece{} 4 \DWOPfbreg{} -12 \DWOPpiece{} 4 }
+\vspace{-2\parsep}
+A twelve byte value whose first four bytes reside in register zero,
 whose middle four bytes are unavailable (perhaps due to optimization),
 and whose last four bytes are in memory, 12 bytes before the frame
 base.
@@ -324,40 +327,39 @@ value consists of two parts, given in memory address order: the 4 byte
 value 1 followed by the four byte value computed from the sum of the
 contents of r3 and r4.
 
-\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} }
+\bb
+\descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 }
 The value register 1 contained upon entering the current subprogram is 
 pushed on the stack.
+\eb
 
-\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} \DWOPstackvalue }
-The value register 1 contained upon entering the current subprogram is 
-pushed on the stack. This value is the
-\doublequote{contents} of an otherwise anonymous location.
+\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} }
+\bb
+Same as the previous example
+(push the value register 1 contained upon entering the current subprogram)
+but use the more compact register location description.
+\eb
 
+\bb
 \descriptionitemnl{\DWOPentryvalue{} 2 \DWOPbregone{} 0 \DWOPstackvalue }
-The value register 1 contained upon entering the current subprogram 
-(same as the previous example) is pushed on the stack. This value is the
+\eb
+The value register 1 contained upon entering the current subprogram is 
+pushed on the stack. This value is the
 \doublequote{contents} of an otherwise anonymous location.
 
-This and the previous location description are equivalent;
-the previous one is shorter, however. 
-
-%FIXME: The following gets an undefined control sequence error for reasons unknown... 
-%\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregthirtyone{} \DWOPregone{} \DWOPadd{} \DWOPstackvalue }
-%The value register 31 had upon entering the current subprogram
-%plus the value register 1 currently has.
+\bb
+\descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregone{} \DWOPstackvalue }
+Same as the previous example (push the value register 1 contained
+upon entering the current subprogram) but use the more compact
+register location description.
+\eb
 
-% Is the following example really interesting enough (not just complicated) to keep?
-\ifthen{\boolean{true}}{
+\needlines{6}
 \descriptionitemnl{\DWOPentryvalue{} 3 \DWOPbregfour{} 16 \DWOPderef{} \DWOPstackvalue }
-%FIXME: similar undefined as just above
-%\descriptionitemnl{\DWOPentryvalue{} 6 \DWOPentryvalue{} 1 \DWOPregfour{} \DWOPplusuconst{} 16 \DWOPderef{} \DWOPstackvalue }
 Add 16 to the value register 4 had upon entering the current subprogram
 to form an address and then push the value of the memory location at that address.
-This value is the
-\doublequote{contents} of an otherwise anonymous location.
-}
+This value is the \doublequote{contents} of an otherwise anonymous location.
 
-\needlines{6}
 \descriptionitemnl{\DWOPentryvalue{} 1 \DWOPregfive{} \DWOPplusuconst{} 16 }
 The address of the memory location is calculated by adding 16 to the value
 contained in register 5 upon entering the current subprogram.
@@ -1821,7 +1823,7 @@ void g() {
                 \DWATname("f")
                 \DWATrvaluereference(0x01)
                 \DWTAGformalparameter
-                    \DWATtype({ref to 200$})    ! to const A*
+                    \DWATtype({ref to 200$})     ! to const A*
                     \DWATartificial(0x01)
 
 200$:   ! const A*
@@ -1834,7 +1836,7 @@ void g() {
 
 400$:   ! mfptr
         \DWTAGptrtomembertype
-            \DWATtype({ref to 400$})             ! to functype
+            \DWATtype({ref to 500$})             ! to functype
             \DWATcontainingtype({ref to 100$})  ! to class A
 
 500$:   ! functype
@@ -1851,7 +1853,7 @@ void g() {
                 \DWATtype({ref to 100$})         ! to class A
             \DWTAGvariable
                 \DWATname("pointer_to_member_function")
-                \DWATtype({ref to 300$})
+                \DWATtype({ref to 400$})
          
 \end{alltt}
 \end{dwflisting}
index 3cf6959..f5d579f 100644 (file)
@@ -74,7 +74,7 @@ Michael Eager, Chair    & Eager Consulting\\
 Jini Susan George       & Hewlett-Packard\\
 Mathhew Gretton-Dan     & ARM\\
 Tommy Hoffner           & Altera\\
-Jakub Jelinek           & Red Hat\\
+Jakub Jel\'{i}nek       & Red Hat\\
 Andrew Johnson          & Linaro\\
 Jason Merrill           & Red Hat\\
 Jason Molenda           & Apple\\
index fe8333b..7376538 100644 (file)
@@ -303,13 +303,7 @@ The attributes are listed in Table \referfol{tab:attributenames}.
 &\livelinki{chap:DWATcalllineofcallsite}
            {Line containing call site of non-inlined call} 
            {line containing call site of non-inlined call} \\
-\DWATcallingconventionTARG{} 
-&\livelinki{chap:DWATcallingconventionforsubprograms}
-           {Calling convention for subprograms}
-           {Calling convention!for subprograms} \\
-&\livelinki{chap:DWATcallingconventionfortypes}
-           {Calling convention for types}
-           {Calling convention!for types} \\
+\bbeb
 \DWATcalloriginTARG{}
 &\livelinki{chap:DWATcalloriginofcallsite}
            {Subprogram called in a call}
@@ -350,6 +344,16 @@ The attributes are listed in Table \referfol{tab:attributenames}.
            {Argument value passed in a call}
            {argument value passed}
            \index{call site!argument value passed} \\
+\bb
+\DWATcallingconventionTARG{} 
+&\livelinki{chap:DWATcallingconventionforsubprograms}
+           {Calling convention for subprograms}
+           {Calling convention!for subprograms} \\
+&\livelinki{chap:DWATcallingconventionfortypes}
+           {Calling convention for types}
+           {Calling convention!for types}
+\eb
+\\
 \DWATcommonreferenceTARG
 &\livelinki{chap:commonreferencecommonblockusage}
         {Common block usage}
@@ -660,7 +664,7 @@ The attributes are listed in Table \referfol{tab:attributenames}.
         {subroutine return address save location} \\
 \bb
 \DWATrnglistsbaseTARG
-&\livelinki{chap:DWATrnglistsbase}
+&\livelinki{chap:DWATrnglistsbaseforrnglists}
         {Base offset for range lists}
         {ranges lists} 
 \eb     
@@ -1691,17 +1695,25 @@ upon entering the current subprogram.  It has two operands: an
 unsigned LEB128\addtoindexx{LEB128!unsigned} length, followed by 
 a block containing a DWARF expression or a register location description 
 (see Section \refersec{chap:registerlocationdescriptions}).  
-The length operand specifies the length
-in bytes of the block.  If the block contains a register location
-description, \DWOPentryvalueNAME{} pushes the value that register had upon
-entering the current subprogram.  If the block contains a DWARF expression,
+The length operand specifies the length in bytes of the block.  
+\bb
+If the block contains a DWARF expression,
 the DWARF expression is evaluated as if it has been evaluated upon entering
 the current subprogram.  The DWARF expression 
 assumes no values are present on the DWARF stack initially and results
 in exactly one value being pushed on the DWARF stack when completed.
+If the block contains a register location
+description, \DWOPentryvalueNAME{} pushes the value that register had upon
+entering the current subprogram. 
+\eb
 
 \DWOPpushobjectaddress{} is not meaningful inside of this DWARF operation.
 
+\textit{\bb 
+The register location description provides a more compact form for the
+case where the value was in a register on entry to the subprogram.
+\eb}
+
 \textit{The values needed to evaluate \DWOPentryvalueNAME{} could be obtained in
 several ways. The consumer could suspend execution on entry to the
 subprogram, record values needed by \DWOPentryvalueNAME{} expressions within
@@ -2069,6 +2081,7 @@ location description that specifies the location of
 an object that is valid when no bounded location description
 applies.
 
+\needlines{6}
 \item \definition{Base address}.\addtoindexx{base address!of location list}
 This kind of entry provides an address to be
 used as the base address for beginning and ending address
index 2f3c6be..86210c0 100644 (file)
@@ -189,8 +189,10 @@ indicating the source language of the compilation
 unit. The set of language names and their meanings are given
 in Table \refersec{tab:languagenames}.
 
+\vspace{1cm}
+\needlines{8}
 \begin{centering}
-  \setlength{\extrarowheight}{0.1cm}
+\setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|l}
   \caption{Language names} \label{tab:languagenames} \\
   \hline \bfseries Language name & \bfseries Meaning \\ \hline
index 745172b..a227021 100644 (file)
@@ -1081,13 +1081,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 
@@ -1120,7 +1120,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 \\
@@ -1128,14 +1128,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 \\