Incorporate changes through March 2014, except for
authorRon Brender <ron.brender@gmail.com>
Thu, 17 Apr 2014 19:55:02 +0000 (15:55 -0400)
committerRon Brender <ron.brender@gmail.com>
Thu, 17 Apr 2014 19:55:02 +0000 (15:55 -0400)
100909.2 (DW_CALL_call_site) and parts of Appendix B.

refer.py changes:
1) use io.path.join to make OS independent
2) fix handling of DW*MARK names (to act like targets)
3) tweak output to make easier to use

Signed-off-by: Ron Brender <ron.brender@gmail.com>
13 files changed:
dwarf5/latexdoc/attributesbytag.tex
dwarf5/latexdoc/changesummary.tex
dwarf5/latexdoc/datarepresentation.tex
dwarf5/latexdoc/debugsectionrelationships.tex
dwarf5/latexdoc/dwarf5.tex
dwarf5/latexdoc/dwarfnamecmds.tex
dwarf5/latexdoc/generaldescription.tex
dwarf5/latexdoc/otherdebugginginformation.tex
dwarf5/latexdoc/programscope.tex
dwarf5/latexdoc/sectionversionnumbers.tex
dwarf5/latexdoc/splitobjects.tex
dwarf5/latexdoc/typeentries.tex
dwarf5/tools/refer.py

index ec6e568..41136a8 100644 (file)
@@ -164,7 +164,7 @@ means include all three of the
 &\DWAThighpc{} \\
 &\DWATlanguage{} \\
 &\DWATlowpc{} \\
-&\DWATmacroinfo{} \\
+&\DWATmacros{} \\
 &\DWATmainsubprogram{} \\
 &\DWATname{} \\
 &\DWATproducer{} \\
@@ -486,7 +486,7 @@ means include all three of the
 &\DWAThighpc{}  \\
 &\DWATlanguage{}  \\
 &\DWATlowpc{}  \\
-&\DWATmacroinfo{}  \\
+&\DWATmacros{}  \\
 &\DWATmainsubprogram{}  \\
 &\DWATname{}  \\
 &\DWATproducer{}  \\
@@ -783,9 +783,9 @@ means include all three of the
 &\DWATname{}   \\
 &\DWATsibling{}   \\
 &\DWATsignature{}   \\
-&\DWATspecification{}   \\
-&\DWATstartscope{}   \\
-&\DWATvisibility{}   \\
+&\DWATspecification{}   \\*
+&\DWATstartscope{}   \\*
+&\DWATvisibility{}   \\*
 
 \hline
 \DWTAGunspecifiedparameters
index 08d268d..f66662a 100644 (file)
@@ -11,11 +11,13 @@ Note
 This change summary is included only in draft versions of this document.
 \end{center}
 
-%\vspace{1cm}
+\vspace{1cm}
 \begin{longtable}{ll}
 \textbf{Date}  & \textbf{Issue Incorporated or Other Change}   \\ \hline       \\
 \endhead
-4/14/2014       & 130526.1 (Type unit merge) \\
+4/17/2014       & 110722.1 (.debug\_macro), Clean up missing target issues \\
+4/15/2014       & 140129.1 (Rust), 140203.1 (hashing of \DWFORMexprlocNAME) \\
+4/14/2014       & 130526.1 (Type unit merge), Fix miscellaneous typos  \\
 2/8/2014        & 131113.1 (UTF-8), 131113.2 (correct \DWTAGtypeunitNAME{} in Appendix A),      \\
                 & 131217.1 (C++ "auto" return type), 131105.1 (add example)     \\
 12/18/2013      & 131105.1 (\&- and \&\&-qualification), 131216.1 (non-defining wording), \\
@@ -49,6 +51,5 @@ This change summary is included only in draft versions of this document.
 6/1/2013       & Begin V5 (from V4.1), delete V4 vs V3 stuff, delete "new in V4" \\
 (Pre-V5)       & 100923.1 (bungled subheader), 101015.1 (sig8 typo), \\
                        & 110404.1 (DW\_TAG\_member typos) \\
-
 \end{longtable}
 \end{abstract}
index a122ae8..ba2b690 100644 (file)
@@ -23,19 +23,18 @@ The labels denoting the beginning and end of the reserved
 \hypertarget{chap:DWXXXlohiuser}{}
 value range for vendor specific extensions consist of the
 appropriate prefix 
-(\DWTAGlouserMARK\DWTAGhiuserMARK{}    DW\_TAG, 
-\DWATlouserMARK\DWAThiuserMARK{}       DW\_AT,
-\DWENDlouserMARK\DWENDhiuserMARK{}     DW\_END, 
-\DWATElouserMARK\DWATEhiuserMARK{}     DW\_ATE, 
-\DWOPlouserMARK\DWOPhiuserMARK{}       DW\_OP, 
-\DWLANGlouserMARK\DWLANGhiuserMARK{}DW\_LANG, 
-\DWLNElouserMARK\DWLNEhiuserMARK{}     DW\_LNE, 
-\DWCClouserMARK\DWCChiuserMARK{}       DW\_CC or 
-\DWCFAlouserMARK\DWCFAhiuserMARK{}     DW\_CFA 
+(\DWATlouserMARK{}\DWAThiuserMARK{}        DW\_AT,
+\DWATElouserMARK{}\DWATEhiuserMARK{}   DW\_ATE, 
+\DWCClouserMARK{}\DWCChiuserMARK{}         DW\_CC,
+\DWCFAlouserMARK{}\DWCFAhiuserMARK{}   DW\_CFA 
+\DWENDlouserMARK{}\DWENDhiuserMARK{}   DW\_END, 
+\DWLANGlouserMARK{}\DWLANGhiuserMARK{}  DW\_LANG, 
+\DWLNElouserMARK{}\DWLNEhiuserMARK{}   DW\_LNE, 
+\DWMACROlouserMARK{}\DWMACROhiuserMARK{}DW\_MACRO,
+\DWOPlouserMARK{}\DWOPhiuserMARK{}         DW\_OP or
+\DWTAGlouserMARK{}\DWTAGhiuserMARK{}   DW\_TAG, 
 respectively) followed by
 \_lo\_user or \_hi\_user. 
-\textit{For example, for DIE tags, the special
-labels are \DWTAGlouserNAME{} and \DWTAGhiuserNAME.}
 Values in the  range between \textit{prefix}\_lo\_user 
 and \textit{prefix}\_hi\_user inclusive,
 are reserved for vendor specific extensions. Vendors may
@@ -43,6 +42,9 @@ use values in this range without conflicting with current or
 future system\dash defined values. All other values are reserved
 for use by the system.
 
+\textit{For example, for DIE tags, the special
+labels are \DWTAGlouserNAME{} and \DWTAGhiuserNAME.}
+
 \textit{There may also be codes for vendor specific extensions
 between the number of standard line number opcodes and
 the first special line number opcode. However, since the
@@ -202,7 +204,7 @@ A skeleton line table (for the type units), in the
 \dotdebuglinedwo{} section (see 
 Section \refersec{chap:skeletoncompilationunitentries}).
 
-\item Macro information, in the \dotdebugmacinfodwo{} section.
+\item Macro information, in the \dotdebugmacrodwo{} section.
 
 \item A string table, in the \dotdebugstrdwo{} section.
 
@@ -486,6 +488,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}) \\
 A 
 \addtoindexx{section offset!in .debug\_info header}
@@ -558,6 +561,7 @@ the \thirtytwobitdwarfformat, this is a 4\dash byte unsigned length;
 in the \sixtyfourbitdwarfformat, this is an 8\dash byte unsigned length
 (see Section \refersec{datarep:32bitand64bitdwarfformats}).
 
+\needlines{4}
 \item \texttt{address\_size} (ubyte) \\
 A 1\dash byte unsigned integer representing the size 
 \addtoindexx{size of an address}
@@ -867,6 +871,21 @@ The index is relative to the value of the \DWATaddrbase{} attribute
 of the associated compilation unit.
 \end{itemize}
 
+\needlines{5}
+\item \livelink{chap:classaddrptr}{addrptr} \\
+\livetarg{datarep:classaddrptr}{}
+This is an offset into the \dotdebugaddr{} section (\DWFORMsecoffset). It
+consists of an offset from the beginning of the \dotdebugaddr{} section to the
+beginning of the list of machine addresses information for the
+referencing entity. It is relocatable in
+a relocatable object file, and relocated in an executable or
+shared object. In the \thirtytwobitdwarfformat, this offset
+is a 4\dash byte unsigned value; in the 64\dash bit DWARF
+format, it is an 8\dash byte unsigned value (see Section
+\refersec{datarep:32bitand64bitdwarfformats}).
+
+\textit{This class is new in \DWARFVersionV.}
+
 \needlines{4}
 \item \livelink{chap:classblock}{block} \\
 \livetarg{datarep:classblock}{}
@@ -1002,13 +1021,12 @@ in the \sixtyfourbitdwarfformat, it is an 8\dash byte unsigned value
 This is an 
 \addtoindexx{section offset!in class macptr value}
 offset into the 
-\dotdebugmacinfo{} or \dotdebugmacinfo{} section
+\dotdebugmacro{} or \dotdebugmacrodwo{} section
 (\DWFORMsecoffset). 
-It consists of an offset from the
-beginning of the \dotdebugmacinfo{} 
-section to the first byte of
-the data making up the macro information list for the compilation
-unit. 
+It consists of an offset from the beginning of the 
+\dotdebugmacro{} or \dotdebugmacrodwo{} 
+section to the the header making up the 
+macro information list for the compilation unit. 
 It is relocatable in a relocatable object file, and
 relocated in an executable or shared object. In the 
 \thirtytwobitdwarfformat, this offset is a 4\dash byte unsigned value;
@@ -1171,6 +1189,21 @@ information about the characters and their use.}
 of strings; for compatibility, this version also does
 not. However, the UTF\dash 8 representation is strongly recommended.}
 
+\item \livelinki{chap:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class} \\
+\livetarg{datarep:classstroffsetsptr}{}
+This is an offset into the \dotdebugstroffsets{} section 
+(\DWFORMsecoffset). It consists of an offset from the beginning of the 
+\dotdebugstroffsets{} section to the
+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. In the \thirtytwobitdwarfformat, this offset
+is a 4\dash byte unsigned value; in the 64\dash bit DWARF
+format, it is an 8\dash byte unsigned value (see Section
+\refersec{datarep:32bitand64bitdwarfformats}).
+
+\textit{This class is new in \DWARFVersionV.}
+
 \end{itemize}
 
 In no case does an attribute use 
@@ -1326,8 +1359,11 @@ Table \refersec{tab:attributeformencodings}.
             \addtoindexx{friend attribute!encoding}  \\
 \DWATidentifiercase&0x42&\livelink{chap:classconstant}{constant} 
             \addtoindexx{identifier case attribute!encoding}  \\
-\DWATmacroinfo&0x43&\livelink{chap:classmacptr}{macptr} 
-            \addtoindexx{macro information attribute!encoding}  \\
+\DWATmacroinfo\footnote{\raggedright Not used in \DWARFVersionV. 
+                        Reserved for compatibility and coexistence
+                        with prior DWARF versions.}
+            &0x43&\livelink{chap:classmacptr}{macptr} 
+            \addtoindexx{macro information attribute (legacy)!encoding}  \\
 \DWATnamelistitem&0x44&\livelink{chap:classreference}{reference} 
             \addtoindexx{name list item attribute!encoding}  \\
 \DWATpriority&0x45&\livelink{chap:classreference}{reference} 
@@ -1435,27 +1471,31 @@ Table \refersec{tab:attributeformencodings}.
                \livelink{chap:classconstant}{constant}
             \addtoindexx{string length attribute!size of length}  \\
 \DWATrank~\ddag&0x71&
-               \livelink{chap:DWATrank}{constant, exprloc}
+        \livelink{chap:classconstant}{constant},
+        \livelink{chap:classexprloc}{exprloc}
             \addtoindexx{rank attribute!encoding}  \\
 \DWATstroffsetsbase~\ddag&0x72&
-               \livelink{chap:classstring}{reference}
+               \livelinki{chap:classstring}{stroffsetsptr}{stroffsetsptr class}
             \addtoindexx{string offsets base!encoding} \\
 \DWATaddrbase~\ddag &0x73&
-               \livelink{chap:DWATaddrbase}{reference}
+               \livelinki{chap:DWATaddrbase}{addrptr}{addrptr class}
             \addtoindexx{address table base!encoding} \\
 \DWATrangesbase~\ddag&0x74&
-               \livelink{chap:DWATrangesbase}{reference}
+               \livelinki{chap:DWATrangesbase}{rangelistptr}{rangelistptr class}
             \addtoindexx{ranges base!encoding} \\
 \DWATdwoid~\ddag &0x75&
                \livelink{chap:DWATdwoid}{constant}
             \addtoindexx{split DWARF object id!encoding} \\
 \DWATdwoname~\ddag &0x76&
-               \livelink{chap:DWATdwname}{string}
+               \livelink{chap:DWATdwoname}{string}
             \addtoindexx{split DWARF object file name!encoding} \\
 \DWATreference~\ddag &0x77&
         \livelink{chap:DWATreference}{flag} \\
 \DWATrvaluereference~\ddag &0x78&
         \livelink{chap:DWATrvaluereference}{flag} \\
+\DWATmacros~\ddag &0x79&\livelink{chap:classmacptr}{macptr} 
+            \addtoindexx{macro information attribute!encoding}  \\
+
 \DWATlouser&0x2000 & --- \addtoindexx{low user attribute encoding}  \\
 \DWAThiuser&\xiiifff& --- \addtoindexx{high user attribute encoding}  \\
 
@@ -1473,9 +1513,9 @@ Table \refersec{tab:attributeformencodings}.
 \endhead
   \hline \emph{Continued on next page}
 \endfoot
-  \hline
-
+  \hline \ddag\ \textit{New in DWARF Version 5}
 \endlastfoot
+
 \DWFORMaddr &0x01&\livelink{chap:classaddress}{address}  \\
 \textit{Reserved} &0x02& \\
 \DWFORMblocktwo &0x03&\livelink{chap:classblock}{block} \\
@@ -1501,10 +1541,10 @@ Table \refersec{tab:attributeformencodings}.
 \DWFORMsecoffset{} &0x17&\livelink{chap:classlineptr}{lineptr}, \livelink{chap:classloclistptr}{loclistptr}, \livelink{chap:classmacptr}{macptr}, \livelink{chap:classrangelistptr}{rangelistptr} \\
 \DWFORMexprloc{} &0x18&\livelink{chap:classexprloc}{exprloc} \\
 \DWFORMflagpresent{} &0x19&\livelink{chap:classflag}{flag} \\
-\DWFORMstrx &0x1a&\livelink{chap:classstring}{string} \\
-\DWFORMaddrx &0x1b&\livelink{chap:classaddess}{address} \\
+\DWFORMstrx{} \ddag &0x1a&\livelink{chap:classstring}{string} \\
+\DWFORMaddrx{} \ddag &0x1b&\livelink{chap:classaddress}{address} \\
 \DWFORMrefsigeight &0x20&\livelink{chap:classreference}{reference} \\
+
 \end{longtable}
 \end{centering}
 
@@ -2061,6 +2101,7 @@ defined language.
 \DWLANGCpluspluszerothree{} \ddag &0x0019 &0 \\
 \DWLANGCpluspluseleven{} \ddag &0x001a &0 \\
 \DWLANGOCaml{} \ddag &0x001b &0        \\
+\DWLANGRust{} \ddag &0x001c &0 \\
 \DWLANGlouser{} &0x8000 & \\
 \DWLANGhiuser{} &\xffff & \\
 
@@ -2471,34 +2512,40 @@ Table \refersec{tab:linenumberfileentryformatencodings}.
 
 The source line numbers and source file indices encoded in the
 macro information section are represented as unsigned LEB128
-numbers as are the constants in a 
-\DWMACINFOvendorext{} entry.
+numbers.
 
-The macinfo type is encoded as a single byte. 
+The macro information entry type is encoded as a single byte. 
 The encodings 
-\addtoindexx{macinfo types!encoding}
+\addtoindexx{macro information entry types!encoding}
 are given in 
-Table \refersec{tab:macinfotypeencodings}.
+Table \refersec{tab:macroinfoentrytypeencodings}.
 
 
 \begin{centering}
 \setlength{\extrarowheight}{0.1cm}
 \begin{longtable}{l|c}
-  \caption{Macinfo type encodings} \label{tab:macinfotypeencodings}\\
-  \hline \bfseries Macinfo type name&\bfseries Value \\ \hline
+  \caption{Macro information entry type encodings} \label{tab:macroinfoentrytypeencodings}\\
+  \hline \bfseries Macro information entry type name&\bfseries Value \\ \hline
 \endfirsthead
-  \bfseries Macinfo type name&\bfseries Value\\ \hline
+  \bfseries Macro information entry type name&\bfseries Value\\ \hline
 \endhead
   \hline \emph{Continued on next page}
 \endfoot
   \hline
 \endlastfoot
 
-\DWMACINFOdefine&0x01 \\
-\DWMACINFOundef&0x02 \\
-\DWMACINFOstartfile&0x03 \\
-\DWMACINFOendfile&0x04 \\
-\DWMACINFOvendorext&\xff \\
+\DWMACROdefine              &0x01 \\
+\DWMACROundef               &0x02 \\
+\DWMACROstartfile           &0x03 \\
+\DWMACROendfile             &0x04 \\
+\DWMACROdefineindirect      &0x05 \\
+\DWMACROundefindirect       &0x06 \\
+\DWMACROtransparentinclude  &0x07 \\
+% what about 0x08 thru 0x0a??
+\DWMACROdefineindirectx     &0x0b \\
+\DWMACROundefindirectx      &0x0c \\
+\DWMACROlouser              &0xe0 \\
+\DWMACROhiuser              &\xff \\
 
 \end{longtable}
 \end{centering}
@@ -2783,7 +2830,7 @@ in the
 \dotdebuginfo{}, 
 \dotdebugline{}, 
 \dotdebugloc{}, 
-\dotdebugmacinfo{},
+\dotdebugmacro{},
 \dotdebugpubnames{}, 
 \dotdebugpubtypes{}, 
 \dotdebugranges{}, 
@@ -2999,9 +3046,11 @@ the value consists of the form code (encoded as an unsigned
 LEB128 value) followed by the encoding of the value according
 to the form code. To ensure reproducibility of the signature,
 the set of forms used in the signature computation is limited
-to the following: \DWFORMsdata, 
+to the following: 
+\DWFORMsdata, 
 \DWFORMflag, 
 \DWFORMstring,
+\DWFORMexprloc,
 and \DWFORMblock.
 
 \item If the tag in Step 3 is one of \DWTAGpointertype,
index 1fbae16..8cf3bae 100644 (file)
@@ -77,7 +77,7 @@ versus \dotdebuginfodwo).}
 \node(zsectstx) at (12, 10) [sect] {\dotdebugstroffsets};
 \node(zsectloc)        at (12,  8) [sect] {\dotdebugloc{} (m)};
 \node(zsectran)        at (12,  6) [sect] {\dotdebugranges};
-\node(zsectmac)        at (12,  4) [sect] {\dotdebugmacinfo};
+\node(zsectmac)        at (12,  4) [sect] {\dotdebugmacro};
 \node(zsectlin)        at (12,  2) [sect] {\dotdebugline};
 \node(zsectadx) at (12,  0) [sect] {\dotdebugaddr{} (m)};
 
@@ -174,12 +174,12 @@ a range list.
 
 %i
 \needlines{5}
-\item \dotdebuginfo{} to \dotdebugmacinfo \\
+\item \dotdebuginfo{} to \dotdebugmacro \\
 An attribute value of class 
 \livelink{chap:classmacptr}{macptr} (specifically form
 \DWFORMsecoffset) is an 
 offset within the 
-\dotdebugmacinfo{} section
+\dotdebugmacro{} section
 of the beginning of the macro information for the referencing unit.
 
 %j
index 6255a30..63196e2 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}{April 14, 2014}
+\newcommand{\docdate}{April 17, 2014}
 %
 \usepackage{ifthen}
 \newboolean{isdraft}
@@ -64,9 +64,11 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \usetikzlibrary{arrows}
 \usepackage{makeidx}       % For making an index
 % hyperref must be the last package listed.
-% The hyperref settings helps hypertext get right links in the 
-% pdf of the index.
-\usepackage[plainpages=false,pdfpagelabels,pagebackref,allcolors=blue]{hyperref} % Lets us generate colored active links inside a pdf.
+% The hyperref settings helps hypertext get links right in the 
+% pdf of the index. 
+% Also, allcolors lets us generate colored active links inside a pdf.
+% And breaklinks resolves truncation issues with very long link names.
+\usepackage[breaklinks,plainpages=false,pdfpagelabels,pagebackref,allcolors=blue]{hyperref} 
 \makeindex  % This and the makeidx package allow \index to create index entries.
 
 \newcommand{\dwf}{DWARF Debugging Information Format}
@@ -287,7 +289,7 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
                \include{changesummary}
                }
        }{}
-
+\cleardoublepage
 \flushleft
 \raggedbottom
 \chapterstyle{default}
@@ -313,14 +315,14 @@ escapeinside={\%*}{*)}     % if you want to add a comment within your code
 \include{dataobject}                    \emptypage
 \include{typeentries}                   %\emptypage
 \include{otherdebugginginformation}    \emptypage
-\include{datarepresentation}            %\emptypage
+\include{datarepresentation}            \emptypage
 
 %  The \appendix toggles us into appendix chapters
 \appendix
 
 \include{attributesbytag}                              \emptypage
-\include{debugsectionrelationships}     %\emptypage
-\include{encodingdecoding}              \emptypage
+\include{debugsectionrelationships}     \emptypage
+\include{encodingdecoding}              %\emptypage
 \include{examples}                      %\emptypage
 \include{compression}                   %\emptypage
 \include{splitobjects}                                 %\emptypage
index 390e7c6..18b5fc4 100644 (file)
@@ -8,7 +8,7 @@
 \newcommand{\newdwfnamecommands}[2]{
        \expandafter\def\csname #1LINK\endcsname{\index{#2}\hyperlink{chap:#1}{#2}}
        \expandafter\def\csname #1TARG\endcsname{\index{#2}\hypertarget{chap:#1}{#2}}
-       \expandafter\def\csname #1INDX\endcsname{\index{#2}#2}
+       \expandafter\def\csname #1INDX\endcsname{\index{#2}}
        \expandafter\def\csname #1MARK\endcsname{\hypertarget{chap:#1}{}\index{#2}}     
        \expandafter\def\csname #1NAME\endcsname{#2}
        % The normal, most common use in running text...
 \newdwfnamecommands{DWATlowerbound}{DW\_AT\_lower\_bound}
 %
 \newdwfnamecommands{DWATmacroinfo}{DW\_AT\_macro\_info}
+\newdwfnamecommands{DWATmacros}{DW\_AT\_macros}
 \newdwfnamecommands{DWATmainsubprogram}{DW\_AT\_main\_subprogram}
 \newdwfnamecommands{DWATmutable}{DW\_AT\_mutable}
 %
 \newdwfnamecommands{DWLANGPascaleightythree}{DW\_LANG\_Pascal83}
 \newdwfnamecommands{DWLANGPLI}{DW\_LANG\_PLI}
 \newdwfnamecommands{DWLANGPython}{DW\_LANG\_Python}
+\newdwfnamecommands{DWLANGRust}{DW\_LANG\_Rust}
 \newdwfnamecommands{DWLANGUPC}{DW\_LANG\_UPC}
 \newdwfnamecommands{DWLANGCpluspluszerothree}{DW\_LANG\_C\_plus\_plus\_03}
 \newdwfnamecommands{DWLANGCpluspluseleven}{DW\_LANG\_C\_plus\_plus\_11}
 \newdwfnamecommands{DWLNSsetisa}{DW\_LNS\_set\_isa}
 \newdwfnamecommands{DWLNSsetprologueend}{DW\_LNS\_set\_prologue\_end}
 %
-% DW_MACINFO
+% DW_MACINFO (Not used in DWARF V5)
 %
-\newdwfnamecommands{DWMACINFOdefine}{DW\_MACINFO\_define}
-\newdwfnamecommands{DWMACINFOendfile}{DW\_MACINFO\_end\_file}
-\newdwfnamecommands{DWMACINFOstartfile}{DW\_MACINFO\_start\_file}
-\newdwfnamecommands{DWMACINFOundef}{DW\_MACINFO\_undef}
-\newdwfnamecommands{DWMACINFOvendorext}{DW\_MACINFO\_vendor\_ext}
+%\newdwfnamecommands{DWMACINFOdefine}{DW\_MACINFO\_define}
+%\newdwfnamecommands{DWMACINFOendfile}{DW\_MACINFO\_end\_file}
+%\newdwfnamecommands{DWMACINFOstartfile}{DW\_MACINFO\_start\_file}
+%\newdwfnamecommands{DWMACINFOundef}{DW\_MACINFO\_undef}
+%\newdwfnamecommands{DWMACINFOvendorext}{DW\_MACINFO\_vendor\_ext}
+%
+% DW_MACRO
+%
+\newdwfnamecommands{DWMACROdefine}{DW\_MACRO\_define}
+\newdwfnamecommands{DWMACROundef}{DW\_MACRO\_undef}
+\newdwfnamecommands{DWMACROstartfile}{DW\_MACRO\_start\_file}
+\newdwfnamecommands{DWMACROendfile}{DW\_MACRO\_end\_file}
+\newdwfnamecommands{DWMACROdefineindirect}{DW\_MACRO\_define\_indirect}
+\newdwfnamecommands{DWMACROundefindirect}{DW\_MACRO\_undef\_indirect}
+\newdwfnamecommands{DWMACROtransparentinclude}{DW\_MACRO\_transparent\_include}
+\newdwfnamecommands{DWMACROdefineindirectx}{DW\_MACRO\_define\_indirectx}
+\newdwfnamecommands{DWMACROundefindirectx}{DW\_MACRO\_undef\_indirectx}
+\newdwfnamecommands{DWMACROlouser}{DW\_MACRO\_lo\_user}
+\newdwfnamecommands{DWMACROhiuser}{DW\_MACRO\_hi\_user}
 %
 % DW_OP
 %
 \newcommand{\dotdebuginfo}{\addtoindex{\texttt{.debug\_info}}}
 \newcommand{\dotdebugline}{\addtoindex{\texttt{.debug\_line}}}
 \newcommand{\dotdebugloc}{\addtoindex{\texttt{.debug\_loc}}}
-\newcommand{\dotdebugmacinfo}{\addtoindex{\texttt{.debug\_macinfo}}}
+\newcommand{\dotdebugmacinfo}{\addtoindex{\texttt{.debug\_mac\_info}}}
 \newcommand{\dotdebugmacro}{\addtoindex{\texttt{.debug\_macro}}}
 \newcommand{\dotdebugpubnames}{\addtoindex{\texttt{.debug\_pubnames}}}
 \newcommand{\dotdebugpubtypes}{\addtoindex{\texttt{.debug\_pubtypes}}}
 \newcommand{\dotdebuginfodwo}{\addtoindex{\texttt{.debug\_info.dwo}}}
 \newcommand{\dotdebuglinedwo}{\addtoindex{\texttt{.debug\_line.dwo}}}
 \newcommand{\dotdebuglocdwo}{\addtoindex{\texttt{.debug\_loc.dwo}}}
-\newcommand{\dotdebugmacinfodwo}{\addtoindex{\texttt{.debug\_macinfo.dwo}}}
+%newcommand{\dotdebugmacinfodwo}{\addtoindex{\texttt{.debug\_macinfo.dwo}}}
 \newcommand{\dotdebugmacrodwo}{\addtoindex{\texttt{.debug\_macro.dwo}}}
 \newcommand{\dotdebugpubnamesdwo}{\addtoindex{\texttt{.debug\_pubnames.dwo}}}
 \newcommand{\dotdebugpubtypesdwo}{\addtoindex{\texttt{.debug\_pubtypes.dwo}}}
 \newcommand{\DWARFVersionIV}  {\addtoindex{DWARF Version 4}}
 \newcommand{\DWARFVersionV}   {\addtoindex{DWARF Version 5}}
 %
+% DWARF Classes of Attribute Value
+%
+\newcommand{\CLASSaddress}      {\addtoindexi{address}{address class}}
+\newcommand{\CLASSaddrptr}      {\addtoindexi{addrptr}{addrptr class}}
+\newcommand{\CLASSblock}        {\addtoindexi{block}{block class}}
+\newcommand{\CLASSconstant}     {\addtoindexi{constant}{constant class}}
+\newcommand{\CLASSexprloc}      {\addtoindexi{exprloc}{exprloc class}}
+\newcommand{\CLASSflag}         {\addtoindexi{flag}{flag class}}
+\newcommand{\CLASSlineptr}      {\addtoindexi{lineptr}{lineptr class}}
+\newcommand{\CLASSloclistptr}   {\addtoindexi{loclistptr}{loclistptr class}}
+\newcommand{\CLASSmacptr}       {\addtoindexi{macptr}{macptr class}}
+\newcommand{\CLASSrangelistptr} {\addtoindexi{rangelistptr}{rangelistptr class}}
+\newcommand{\CLASSreference}    {\addtoindexi{reference}{reference class}}
+\newcommand{\CLASSstring}       {\addtoindexi{string}{string class}}
+\newcommand{\CLASSstroffsetsptr}{\addtoindexi{stroffsetsptr}{stroffsetsptr class}}
+%
 % Miscellaneous
 %
 \newcommand{\MDfive}{\livelink{def:MDfive}{MD5}}
index 20813e8..0f40da8 100644 (file)
@@ -273,7 +273,7 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \DWATdwoidTARG
 &\livelinki{chap:DWATdwoidforunit}{Signature for compilation unit}{split DWARF object file!unit signature} \\
 \DWATdwonameTARG
-&\livelinki{chap:DWATdwoidforunit}{Name of split DWARF object file}{split DWARF object file!object file name} \\
+&\livelinki{chap:DWATdwonameforunit}{Name of split DWARF object file}{split DWARF object file!object file name} \\
 \DWATelementalTARG
 &\livelinki{chap:DWATelementalelementalpropertyofasubroutine}{Elemental property of a subroutine}{elemental property of a subroutine} \\
 \DWATencodingTARG
@@ -321,7 +321,9 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \DWATlowerboundTARG
 &\livelinki{chap:DWATlowerboundlowerboundofsubrange}{Lower bound of subrange}{lower bound of subrange} \\
 \DWATmacroinfoTARG
-&\livelinki{chap:DWATmacroinfomacroinformation}{Macro information} {macro information} (\texttt{\#define}, \texttt{\#undef})\\
+&\livelinki{chap:DWATmacroinfomacroinformation}{Macro information (for pre-\DWARFVersionV{} compatibility)} {macro information (legacy)} \\
+\DWATmacrosTARG
+&\livelinki{chap:DWATmacrosmacroinformation}{Macro information} {macro information} (\texttt{\#define}, \texttt{\#undef}, and so on)\\
 \DWATmainsubprogramTARG
 &\livelinki{chap:DWATmainsubprogrammainorstartingsubprogram}{Main or starting subprogram}{main or starting subprogram} \\
 &\livelinki{chap:DWATmainsubprogramunitcontainingmainorstartingsubprogram}{Unit containing main or starting subprogram}{unit containing main or starting subprogram}\\
@@ -415,6 +417,7 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \end{longtable}
 
 \addtoindexx{address|see {\textit{also} address class}}
+\addtoindexx{addrptr|see {\textit{also} addrptr class}}
 \addtoindexx{block|see {\textit{also} block class}}
 \addtoindexx{constant|see {\textit{also} constant class}}
 \addtoindexx{exprloc|see {\textit{also} exprloc class}}
@@ -425,7 +428,10 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \addtoindexx{rangelistptr|see {\textit{also} rangelistptr class}}
 \addtoindexx{reference|see {\textit{also} reference class}}
 \addtoindexx{string|see {\textit{also} string class}}
+\addtoindexx{stroffsetsptr|see {\textit{also} stroffsetsptr class}}
+
 \addtoindexx{class of attribute value!address|see {address class}}
+\addtoindexx{class of attribute value!addrptr|see {addrptr class}}
 \addtoindexx{class of attribute value!block|see {block class}}
 \addtoindexx{class of attribute value!constant|see {constant class}}
 \addtoindexx{class of attribute value!exprloc|see {exprloc class}}
@@ -436,20 +442,34 @@ to one of the classes shown in Table \refersec{tab:classesofattributevalue}.
 \addtoindexx{class of attribute value!rangelistptr|see {rangelistptr class}}
 \addtoindexx{class of attribute value!reference|see {reference class}}
 \addtoindexx{class of attribute value!string|see {string class}}
+\addtoindexx{class of attribute value!stroffsetsptr|see {stroffsetsptr class}}
 
-\begin{table}[here]
+
+\begin{longtable}{l|p{11cm}}
 \caption{Classes of attribute value}
-\label{tab:classesofattributevalue}
-\centering
-\setlength{\extrarowheight}{0.1cm}
+\label{tab:classesofattributevalue} \\
+\hline \bfseries Attribute Class & \bfseries General Use and Encoding \\ \hline
+\endfirsthead
+  \bfseries Attribute Class & \bfseries General Use and Encoding \\ \hline
+\endhead
+  \hline \emph{Continued on next page}
+\endfoot
+  \hline
+\endlastfoot
 
-\begin{tabular}{l|p{11cm}} \hline
-Attribute Class & General Use and Encoding \\ \hline
 \hypertarget{chap:classaddress}{}
 \livelinki{datarep:classaddress}{address}{address class}
 &Refers to some location in the address space of the described program.
 \\
 
+\hypertarget{chap:classaddrptr}{}
+\livelinki{datarep:classaddrptr}{addrptr}{addrptr class}
+&Refers to a base location in the DWARF section that holds
+a series of machine address values. Certain attributes refer
+one of these addresses by indexing relative to this base
+location.
+\\
+
 \hypertarget{chap:classblock}{}
 \livelinki{datarep:classblock}{block}{block class}
 & An arbitrary number of uninterpreted bytes of data.
@@ -524,13 +544,20 @@ printable strings. Strings may be represented directly in
 the debugging information entry or as an offset in a separate
 string table.
 \\
+
+\hypertarget{chap:classstroffsetsptr}{}
+\livelinki{datarep:classstroffsetsptr}{stroffsetsptr}{stroffsetsptr class}
+&Refers to a base location in the DWARF section that holds
+a series of offsets in the DWARF section that holds strings.
+Certain attributes refer one of these offets by indexing 
+relative to this base location. The resulting offset is then 
+used to index into the DWARF string section.
+\\
+
 \hline
-\end{tabular}
-\end{table}
+\end{longtable}
+
 
-% It is difficult to get the above table to appear before
-% the end of the chapter without a clearpage here.
-\clearpage
 \section{Relationship of Debugging Information Entries}
 \label{chap:relationshipofdebugginginformationentries}
 \textit{%
@@ -571,6 +598,7 @@ relations are taken into account, the debugging entries
 form a graph, not a tree.  
 }
 
+\needlines{4}
 The tree itself is represented
 by flattening it in prefix order. 
 Each debugging information
@@ -676,7 +704,7 @@ value is truncated to the element size and the low\dash order bits
 are pushed on the stack.
 \begin{enumerate}[1. ]
 \itembfnl{\DWOPlitzeroTARG, \DWOPlitoneTARG, \dots, \DWOPlitthirtyoneTARG}
-The \DWOPlitnNAME{} operations encode the unsigned literal values
+The \DWOPlitnTARG{} operations encode the unsigned literal values
 from 0 through 31, inclusive.
 
 \itembfnl{\DWOPaddrTARG}
@@ -701,6 +729,7 @@ an unsigned LEB128 integer constant.
 The single operand of the \DWOPconstsNAME{} operation provides
 a signed LEB128 integer constant.
 
+\needlines{4}
 \itembfnl{\DWOPaddrxTARG}
 The \DWOPaddrxNAME{} operation has a single operand that
 encodes an unsigned LEB128 value, which is a zero-based
@@ -980,6 +1009,7 @@ a bitwise or operation on the two, and pushes the result.
 The \DWOPplusTARG{} operation pops the top two stack entries,
 adds them together, and pushes the result.
 
+\needlines{6}
 \itembfnl{\DWOPplusuconstTARG}
 The \DWOPplusuconstTARG{} operation pops the top stack entry,
 adds it to the unsigned LEB128 constant operand and pushes
@@ -1798,7 +1828,7 @@ a type or type modifier (using
 \addtoindexx{type attribute}
 a \DWATtype{} attribute of its
 own). See 
-Section  \refersec{chap:typeentries} 
+Section  \referfol{chap:typeentries} 
 for descriptions of the entries describing
 base types, user-defined types and type modifiers.
 
@@ -1992,6 +2022,7 @@ also a definition, or is otherwise incomplete, to evaluate
 \hypertarget{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}{}
 an expression correctly.
 
+\needlines{10}
 \textit{As an example, consider the following fragment of \addtoindex{C} code:}
 
 \begin{lstlisting}
@@ -2156,6 +2187,7 @@ a
 whose value is a location description
 (see Section \refersec{chap:locationdescriptions}).
 
+\needlines{4}
 A 
 \addtoindex{DWARF procedure}
 is represented by any
@@ -2232,6 +2264,7 @@ historically the \DWATlowpc{} attribute was used before the
 (in \addtoindex{DWARF Version 3}). There is
 insufficient reason to change this.}
 
+\needlines{8}
 \subsection{Continuous Address Range}
 \label{chap:contiguousaddressranges}
 When the set of addresses of a debugging information entry can
@@ -2606,7 +2639,9 @@ describing the type of the parameterized value.
 The entry also has an attribute giving the 
 actual compile-time or run-time constant value 
 of the value parameter for this instantiation.
-This can be a \DWATconstvalue{} attribute, whose
+This can be a 
+\DWATconstvalue{}\livetarg{chap:DWATconstvaluetemplatevalueparameter}{} 
+attribute, whose
 value is the compile-time constant value as represented 
 on the target architecture. 
 Or, the attribute can be a \DWATlocation{} attribute, whose value is a 
index 7484780..a647755 100644 (file)
@@ -1169,50 +1169,102 @@ As described in
 Section \refersec{chap:normalandpartialcompilationunitentries},
 the macro information for a
 given compilation unit is represented in the 
-\dotdebugmacinfo{}
-section of an object file. The macro information for each
-compilation unit is represented as a series of \doublequote{macinfo}
-entries. Each macinfo entry consists of a \doublequote{type code} and
-up to two additional operands. The series of entries for a
+\dotdebugmacro{}
+section of an object file. 
+
+\needlines{4}
+\textit{The \dotdebugmacro{} section is new in 
+\DWARFVersionV, and supersedes the
+\dotdebugmacinfo{} section of earlier DWARF versions. 
+While \dotdebugmacro{} and \dotdebugmacinfo{}
+sections cannot both occur in the same compilation, both may be found in the 
+set of units that make up an executable or shared object.}
+
+\textit{The representation of debugging information in the \dotdebugmacinfo{} section is specified
+in earlier versions of the DWARF standard. Note that the \dotdebugmacinfo{} section does not contain 
+any headers and does not support indirect string encodings or transparent includes (see below).}
+
+The macro information for each
+compilation unit starts with a header followed by a series of 
+\doublequote{macroinfo}
+entries. Each macroinfo entry consists of a \doublequote{type code}
+followed by zero or more operands. The series of entries for a
 given compilation unit ends with an entry containing a type
 code of 0.
 
-\subsection{Macinfo Types}
-\label{chap:macinfotypes}
+The header starts with a 2-byte \texttt{version} field, followed by a
+1-byte \texttt{flags} field. Additional fields may be present, depending
+of the value of the flags \texttt{field}. 
+    
+If the least significant bit (bit 0) (the \texttt{offset\_size} flag) 
+in the \texttt{flags} field is clear, the header is for a 32-bit 
+DWARF format macro section and offsets are 4 bytes long,
+if it is set, the header is for a 64-bit DWARF format macro section 
+and offsets are 8 bytes long.
+
+If the second least significant bit (bit 1) in the \texttt{flags} is set,
+there follows an offset in the \dotdebugline{} section of the
+beginning of the line number information, encoded as 4-byte offset for
+a 32-bit DWARF format macro section and 8-byte offset for a 64-bit DWARF format
+macro section.  
+
+If the third least significant bit (bit 2) in the \texttt{flags} is set, there follows
+an \texttt{opcode\_operands} table describing the operands of the macroinfo entry types.
+The macroinfo entry types defined in this standard may, but need not, be
+described in the table, while other macroinfo entry types used in the section
+are described there.  Vendor extension macroinfo entry types are
+allocated in the range from \DWMACROlouser{} to \DWMACROhiuser. Other
+unassigned codes are reserved for future DWARF standards.
+
+The table starts with a 1-byte \texttt{count} of the defined opcodes, followed by
+an entry for each of those opcodes.  Each entry starts with a 1-byte
+opcode number, followed by unsigned LEB128 encoded number of operands
+and for each operand there is a single byte describing the form in which
+the operand is encoded.  The allowed values are: 
+\DWFORMblock, \DWFORMblockone, \DWFORMblocktwo, \DWFORMblockfour,
+\DWFORMdataone, \DWFORMdatatwo, \DWFORMdatafour, \DWFORMdataeight, 
+\DWFORMsdata, \DWFORMudata, \DWFORMflag, \DWFORMsecoffset,
+\DWFORMstring, \DWFORMstrp{} and \DWFORMstrx.
+
+\textit{The table allows a consumer to skip over unknown macroinfo entry types.}
+
+\needlines{6}
+\subsection{Macroinfo Types}
+\label{chap:macroinfotypes}
 
-The valid \addtoindex{macinfo types} are as follows:
+The valid \addtoindex{macroinfo entry types} are as follows:
 
 \begin{tabular}{ll}
-\DWMACINFOdefine{} 
-&A macro definition\\
-\DWMACINFOundef
-&A macro undefinition\\
-\DWMACINFOstartfile
-&The start of a new source file inclusion\\
-\DWMACINFOendfile
-&The end of the current source file inclusion\\
-\DWMACINFOvendorext
-& Vendor specific macro information directives\\
+\DWMACROdefine{}            &A macro definition\\
+\DWMACROundef               &A macro undefinition\\
+\DWMACROstartfile           &The start of a new source file inclusion\\
+\DWMACROendfile             &The end of the current source file inclusion\\
+\DWMACROdefineindirect      &A macro definition (indirect name string)\\
+\DWMACROundefindirect       &A macro undefinition (indirect name string)\\
+\DWMACROtransparentinclude  &A sequence of macro information entries to include\\
+\DWMACROdefineindirectx     &A macro definition (indexed name string)\\
+\DWMACROundefindirectx      &A macro undefinition (indexed name string)\\
 \end{tabular}
 
 \subsubsection{Define and Undefine Entries}
 \label{chap:defineandundefineentries}
-
-All 
-\DWMACINFOdefineTARG{} and 
-\DWMACINFOundefTARG{} entries have two
-operands. The first operand encodes the line number of the
-source line on which the relevant defining or undefining
-macro directives appeared.
-
+The define and undefine macro entries have three forms that
+use different representations of their two operands.
+
+\textit{While described in pairs below, the forms of define 
+and undefine entries may be freely intermixed.}
+
+\subsubsubsection{Define and Undefine Using Direct Strings}
+\label{chap:defineandundefinedirectentries}
+A \DWMACROdefineTARG{} or
+\DWMACROundefTARG{} entry has two
+operands. The first operand encodes the source line number 
+of the \texttt{\#define} or \texttt{\#undef} macro directive.
 The second operand consists of a null-terminated character
-string. In the case of a 
-\DWMACINFOundef{} entry, the value
-of this string will be simply the name of the pre- processor
-symbol that was undefined at the indicated source line.
+string. 
 
-In the case of a \DWMACINFOdefine{} entry, the value of this
-string will be the name of the macro symbol that was defined
+In the case of a \DWMACROdefineNAME{} entry, the value of the
+second string is the name of the macro symbol that is defined
 at the indicated source line, followed immediately by the 
 \addtoindex{macro formal parameter list}
 including the surrounding parentheses (in
@@ -1222,96 +1274,127 @@ then the name of the defined macro is followed directly by
 its definition string.
 
 In the case of a function-like macro definition, no whitespace
-characters should appear between the name of the defined
+characters appear between the name of the defined
 macro and the following left parenthesis. Also, no whitespace
-characters should appear between successive formal parameters
+characters appear between successive formal parameters
 in the formal parameter list. (Successive formal parameters
 are, however, separated by commas.) Also, exactly one space
-character should separate the right parenthesis that terminates
+character separates the right parenthesis that terminates
 the formal parameter list and the following definition string.
 
-In the case of a \doublequote{normal} (i.e. non-function-like) macro
+In the case of a \doublequote{normal} (that is, non-function-like) macro
 definition, exactly one space character should separate the
 name of the defined macro from the following definition text.
 
-
+In the case of a \DWMACROundefNAME{} entry, the value
+of the second string is the name of the pre-processor
+symbol that is undefined at the indicated source line.
+
+\subsubsubsection{Define and Undefine Using Indirect Strings}
+\label{chap:defineandundefineindirectentries}
+A \DWMACROdefineindirectTARG{} or \DWMACROundefindirectTARG{} entry has
+two operands.  The first operand encodes the line number of the source line
+on which the relevant defining or undefining macro directives appeared.
+The second operand consists of an offset into a string table contained in
+the \dotdebugstr{} section of the object file.  The size of the operand is
+given in the header \texttt{offset\_size} field.  Apart from the
+encoding of the operands these entries are equivalent to \DWMACROdefine{}
+and \DWMACROundef.
+
+\subsubsubsection{Define and Undefine Using Indexed Strings}
+\label{chap:defineandundefineindexedentries}
+A \DWMACROdefineindirectxTARG{} or \DWMACROundefindirectxTARG{} entry has
+two operands.  The first operand encodes the line number of the source line
+on which the relevant defining or undefining macro directives appeared.
+The second operand is represented using an unsigned LEB128 encoded value,
+which is interpreted as a zero-based index into an array of offsets in the
+\dotdebugstroffsets{} section.  Apart from the encoding of the operands 
+these entries are equivalent to \DWMACROdefine{}
+and \DWMACROundef.
 
 \subsubsection{Start File Entries}
 \label{chap:startfileentries}
-Each \DWMACINFOstartfileTARG{} entry also has two operands. The
+A \DWMACROstartfileTARG{} entry has two operands. The
 first operand encodes the line number of the source line on
 which the inclusion macro directive occurred.
+The second operand encodes a source file name index. 
 
-The second operand encodes a source file name index. This index
+The source file name index
 corresponds to a file number in the line number information
 table for the relevant compilation unit. This index indicates
 (indirectly) the name of the file that is being included by
 the inclusion directive on the indicated source line.
 
+If a \DWMACROstartfileNAME{} entry is present, the header
+contains a reference to the \dotdebugline{} section of compilation.
+
 \subsubsection{End File Entries}
 \label{chap:endfileentries}
-A \DWMACINFOendfileTARG{} entry has no operands. The presence of
+A \DWMACROendfileTARG{} entry has no operands. The presence of
 the entry marks the end of the current source file inclusion.
 
-\subsubsection{Vendor Extension Entries}
-\label{chap:vendorextensionentries}
-A \DWMACINFOvendorextTARG{} entry has two operands. The first
-is a constant. The second is a null-terminated character
-string. The meaning and/or significance of these operands is
-intentionally left undefined by this specification.
-
-\textit{A consumer must be able to totally ignore all
-\DWMACINFOvendorext{} entries that it does not understand
-(see Section \refersec{datarep:vendorextensibility}).}
+\subsubsection{Transparent Inclusion of a Sequence of Entries}
+A \DWMACROtransparentincludeTARG{} entry has one operand, an offset into
+another part of the \dotdebugmacro{} section.  The size of the operand
+is given in the header \texttt{offset\_size} field.  The
+\DWMACROtransparentincludeNAME{} macroinfo entry instructs the consumer to 
+replace it with a sequence of macroinfo entries found
+after the section header at the given 
+\dotdebugmacro{} offset, up to, but excluding,
+the terminating entry with type code \texttt{0}.
 
+\textit{The \DWMACROtransparentincludeNAME{} entry type makes it possible 
+to share duplicate sequences of macroinfo entries among different compilation units.}
 
 \subsection{Base Source Entries} 
 \label{chap:basesourceentries}
 
-A producer shall generate \DWMACINFOstartfile{} and
-\DWMACINFOendfile{} entries for the source file submitted to
-the compiler for compilation. This \DWMACINFOstartfile{} entry
+A producer shall generate \DWMACROstartfile{} and
+\DWMACROendfile{} entries for the source file submitted to
+the compiler for compilation. This \DWMACROstartfile{} entry
 has the value 0 in its line number operand and references
 the file entry in the line number information table for the
 primary source file.
 
 
-\subsection{Macinfo Entries For Command Line Options}
+\subsection{Macroinfo Entries For Command Line Options}
 \label{chap:macinfoentriesforcommandlineoptions}
-
-In addition to producing \DWMACINFOdefine{} and \DWMACINFOundef{}
-entries for each of the define and undefine directives
+%\DWMACROdefineINDX{}\DWMACROdefineindirectINDX{}\DWMACROindirectxINDX
+%\DWMACROundefINDX{}\DWMACROundefindirectINDX{}\DWMACROundefindirectxINDX
+In addition to producing define and undefine entries
+(see Section \refersec{chap:defineandundefineentries})
+for each of the define and undefine directives
 processed during compilation, the DWARF producer should
-generate a \DWMACINFOdefine{} or \DWMACINFOundef{} entry for
+generate a define or undefine entry for
 each pre-processor symbol which is defined or undefined by
 some means other than via a define or undefine directive
 within the compiled source text. In particular, pre-processor
-symbol definitions and undefinitions which occur as a
+symbol definitions and undefinitions which occur as a
 result of command line options (when invoking the compiler)
-should be represented by their own \DWMACINFOdefine{} and
-\DWMACINFOundef{} entries.
+should be represented by their own define and
+undefine entries.
 
-All such \DWMACINFOdefine{} and \DWMACINFOundef{} entries
+All such define and undefine entries
 representing compilation options should appear before the
-first \DWMACINFOstartfile{} entry for that compilation unit
+first \DWMACROstartfile{} entry for that compilation unit
 and should encode the value 0 in their line number operands.
 
 
 \subsection{General rules and restrictions}
 \label{chap:generalrulesandrestrictions}
 
-All macinfo entries within a \dotdebugmacinfo{}
+All macroinfo entries within a \dotdebugmacro{}
 section for a
 given compilation unit appear in the same order in which the
 directives were processed by the compiler.
 
-All macinfo entries representing command line options appear
+All macroinfo entries representing command line options appear
 in the same order as the relevant command line options
 were given to the compiler. In the case where the compiler
 itself implicitly supplies one or more macro definitions or
-un-definitions in addition to those which may be specified on
-the command line, macinfo entries are also produced for these
-implicit definitions and un-definitions, and these entries
+undefinitions in addition to those which may be specified on
+the command line, macroinfo entries are also produced for these
+implicit definitions and undefinitions, and these entries
 also appear in the proper order relative to each other and
 to any definitions or undefinitions given explicitly by the
 user on the command line.
@@ -1321,7 +1404,8 @@ user on the command line.
 \section{Call Frame Information}
 \label{chap:callframeinformation}
 
-\textit{Debuggers often need to be able to view and modify the state of any subroutine activation that is
+\textit{Debuggers often need to be able to view and modify the 
+state of any subroutine activation that is
 \addtoindexx{activation!call frame}
 on the call stack. An activation consists of:}
 
@@ -1369,12 +1453,12 @@ the current subroutine to its predecessor. We say that the
 debugger virtually unwinds the stack because the actual state
 of the target process is unchanged.}
 
+\needlines{4}
 \textit{The unwinding operation needs to know where registers are
 saved and how to compute the predecessor\textquoteright s CFA and code
 location. When considering an architecture-independent way
 of encoding this information one has to consider a number of
-special things.}
-
+special things:}
 
 \begin{itemize} % bullet list
 
@@ -1433,6 +1517,7 @@ an architecture specific ABI authoring committee, a hardware
 vendor, or a compiler producer. The body defining a specific
 augmentation is referred to below as the \doublequote{augmenter.}
 
+\needlines{8}
 Abstractly, this mechanism describes a very large table that
 has the following structure:
 
@@ -1456,7 +1541,7 @@ Frame Address value; it may be either a register and a signed
 offset that are added together, or a DWARF expression that
 is evaluated.
 
-The remaining columns are labeled by register number. This
+The remaining columns are labelled by register number. This
 includes some registers that have special designation on
 some architectures such as the PC and the stack pointer
 register. (The actual mapping of registers for a particular
@@ -1612,7 +1697,7 @@ rule table represents the return address of the function. Note
 that this column might not correspond to an actual machine
 register.
 
-\needlines{4}
+\needlines{8}
 \item \texttt{initial\_instructions} (array of \addtoindex{ubyte}) \\
 A sequence of rules that are interpreted to create the initial
 setting of each column in the table.  
index 4ec6587..92398ec 100644 (file)
@@ -166,6 +166,7 @@ Language name & Meaning\\ \hline
 \DWLANGPascaleightythreeTARG & ISO \addtoindex{Pascal}:1983\\
 \DWLANGPLITARG{} \dag & ANSI \addtoindex{PL/I}:1976\\
 \DWLANGPythonTARG{} \dag & \addtoindex{Python}\\
+\DWLANGRustTARG{} \dag & \addtoindex{Rust} \\
 \DWLANGUPCTARG{} & \addtoindex{Unified Parallel C}\addtoindexx{UPC}\\ \hline
 \dag \ \ \textit{Support for these languages is limited.}& \\
 \end{tabular}
@@ -191,21 +192,30 @@ information for this compilation unit
 \clearpage
 
 \needlines{6}
-\item A \DWATmacroinfo{} attribute 
+\item A \DWATmacros{} attribute 
 \addtoindexx{macro information attribute}
 whose value is a 
 \addtoindexx{section offset!in macro information attribute}
 section
-\hypertarget{chap:DWATmacroinfomacroinformation}{}
+\hypertarget{chap:DWATmacrosmacroinformation}{}
 offset to the macro information for this compilation unit.
 
 This information is placed in a separate object file section
 from the debugging information entries themselves. The
 value of the macro information attribute is the offset in
-the \dotdebugmacinfo{} section of the first byte of the macro
+the \dotdebugmacro{} section of the first byte of the macro
 information for this compilation unit 
 (see Section \refersec{chap:macroinformation}).
 
+\textit{The \DWATmacros{} attribute is new in \DWARFVersionV, 
+and supersedes the 
+\DWATmacroinfo{} attribute of earlier DWARF versions.
+\livetarg{chap:DWATmacroinfomacroinformation}{}
+While \DWATmacros{} and \DWATmacroinfo{} attributes cannot both occur in the same
+compilation unit, both may be found in the set of units that make up an executable
+or shared object. The two attributes have distinct encodings to facilitate such
+coexistence.}
+
 \needlines{6}
 \item  A 
 \DWATcompdir{} 
@@ -254,6 +264,7 @@ entries for the compilation unit reflect the names as they
 appear in the source program. The debugger should be sensitive
 to the case of identifier names when doing identifier lookups.
 
+\needlines{4}
 \DWIDupcaseTARG{} means that the 
 producer of the debugging
 information for this compilation unit converted all source
@@ -402,7 +413,7 @@ A \DWATcompdir{} attribute (the same as for regular
 compilation unit entries).
 
 \item
-\livetarg{chap:DWATdwoidforunit}{}
+\livetarg{chap:DWATdwonameforunit}{}
 A \DWATdwonameNAME{} attribute whose value is a
 null-terminated string containing the full or relative
 path name of the DWARF object file that contains the full
@@ -1344,6 +1355,7 @@ a function that is instantiated differently for calls with
 values of different types. DWARF does not represent the generic
 template definition, but does represent each instantiation.}
 
+\needlines{4}
 A \addtoindex{template instantiation} is represented by a debugging
 information entry with the 
 \addtoindexx{subprogram entry!use for template instantiation}
@@ -1964,6 +1976,7 @@ statement is usually the target of one or more \doublequote{go to}
 statements.
 }
 
+\needlines{4}
 A label is represented by a debugging information entry with
 \addtoindexx{label entry}
 the 
@@ -2032,6 +2045,7 @@ a \DWATlocation{} attribute, describing how to find the base
 address of the record object referenced within the body of
 the with statement.
 
+\needlines{6}
 \section{Try and Catch Block Entries}
 \label{chap:tryandcatchblockentries}
 
index 409be34..1ef3850 100644 (file)
@@ -45,7 +45,8 @@ format would be represented by a change in the
 \dotdebuginfo{}     & 2 & 3 & 4 & 5 \\
 \dotdebugline{}     & 2 & 3 & 4 & 5 \\
 \dotdebugloc{}      & - & - & - & 5 \\
-\dotdebugmacinfo{}  & - & - & - & - \\
+\dotdebugmacinfo{}  & - & - & - & x \\
+\dotdebugmacro{}    & x & x & x & 5 \\
 \dotdebugpubnames{} & 2 & 2 & 2 & 2 \\
 \dotdebugpubtypes{} & x & 2 & 2 & 2 \\
 \dotdebugranges{}   & x & - & - & 5 \\
@@ -57,6 +58,7 @@ format would be represented by a change in the
 \dotdebuginfodwo    & x & x & x & 5 \\
 \dotdebuglinedwo    & x & x & x & 5 \\
 \dotdebuglocdwo     & x & x & x & 5 \\
+\dotdebugmacrodwo   & x & x & x & 5 \\
 \dotdebugstrdwo     & x & x & x & - \\
 \dotdebugstroffsetsdwo 
                     & x & x & x & 5 \\
index 5146e35..84f7f91 100644 (file)
@@ -62,8 +62,8 @@ strings referenced by the debugging information in the
 \dotdebugstroffsetsdwo{} - Contains the string offsets table
 for the strings in the \dotdebugstrdwo{}{} section.
 \item
-\dotdebugmacinfodwo{} - Contains macro definition information,
-normally found in the \dotdebugmacinfo{} section.
+\dotdebugmacrodwo{} - Contains macro definition information,
+normally found in the \dotdebugmacro{} section.
 \item
 \dotdebuglinedwo{} - Contains skeleton line tables for the type
 units in the \dotdebuginfodwo{} section. These line tables
index 26b749a..53da8e0 100644 (file)
@@ -1883,9 +1883,9 @@ allocated for the string (as specified by the \DWATbytesize{}
 or \DWATbitsize{} attribute).
 
 The string type entry may also have a 
-\DWATstringlengthbytesizeTARG{}
+\DWATstringlengthbytesizeNAME{}
 attribute or
-\DWATstringlengthbitsizeTARG{} attribute,
+\DWATstringlengthbitsizeNAME{} attribute,
 \addtoindexx{string length attribute!size of length data}
 whose value (see Section \refersec{chap:byteandbitsizes}) 
 is the size of the data to be retrieved from the location
@@ -2034,7 +2034,8 @@ If the lower bound value is missing, the value is assumed to
 be a language\dash dependent default constant. 
 \addtoindexx{lower bound attribute!default}
 The default lower bound is 0 for 
-\addtoindex{C}, \addtoindex{C++}, 
+\addtoindex{C}, 
+\addtoindex{C++}, 
 \addtoindex{D},
 \addtoindex{Go},
 \addtoindex{Haskell}, 
@@ -2042,7 +2043,8 @@ The default lower bound is 0 for
 \addtoindex{Objective C}, 
 \addtoindex{Objective C++},
 \addtoindex{OpenCL},
-\addtoindex{Python}, and 
+\addtoindex{Python}, 
+\addtoindex{Rust}, and 
 \addtoindex{UPC}. 
 The default lower bound is 1 for 
 \addtoindex{Ada}, 
@@ -2360,7 +2362,7 @@ time. The value of the \DWATrankINDX{} attribute is either an integer constant
 or a location expression whose evaluation yields the dynamic rank.
 
 The bounds of an array with dynamic rank are described using the
-\DWTAGgenericsubrangeTARG{} tag, which  
+\DWTAGgenericsubrange{} tag, which  
 is the dynamic rank array equivalent of
 \DWTAGsubrangetype. The
 difference is that a \DWTAGgenericsubrangeINDX{} contains generic
@@ -2384,7 +2386,7 @@ fashion.
 \textit{For an example in Fortran 2008, see
   Section~\refersec{app:assumedrankexample}.}
 
-
+\needlines{6}
 \section{Template Alias Entries}
 \label{chap:templatealiasentries}
 
index 7df2334..a954d45 100644 (file)
@@ -20,6 +20,8 @@
 # The index namespace, which we are not presently filling in very much. 
 
 import sys
+import os
+import os.path
 import fileio
 
 # These two hold the commands we care about so we can
@@ -722,7 +724,8 @@ def transfunc2(linetoks,myfile,linenum):
       # index DWname
       if dwfnamecommsdict.has_key(commandname):
         tm = tokmention(t,myfile,linenum)
-        applytodict(targhyperdict,commandname,tm)
+        targname = makelinkname(commandname)
+        applytodict(targhyperdict,targname,tm)
         indexname = deloptionalprefix(commandname,"\\")
         applytodict(indexdict,indexname,tm)
       else:
@@ -807,19 +810,25 @@ def checkduplicatetargs(dname,d):
         printtoomany(dname,k,v)
 
 def checkmissingtarg(name,targ,refs):
+  n = 0
   rlist = refs.items()
   for r in rlist:
     (k,v) = r
     if targ.has_key(k) == 0:
-       print "target missing from",name,":",k
+       n = n + 1
+       print "Missing target from " + name + ":",k
+  if n == 0: print "No missing targets from " + name +"!"
 
 def checkmissingref(name,targ,refs):
+  n = 0
   rlist = targ.items()
   for r in rlist:
     (k,v) = r
     if refs.has_key(k) == 0:
-       print "Unused target from",name,":",k
-  
+       n = n + 1
+       print "Unused target from " + name + ":",k
+  if n == 0: print "No unused targets from " + name + "..."
+
 def print_stats():
   global dwfnamecommsdict
   global newcommsdict
@@ -834,16 +843,18 @@ def print_stats():
   checkduplicatetargs("hypertargets",targhyperdict)
   checkduplicatetargs("labels",labeldict)
 
-  checkmissingtarg("hyperlinks",targhyperdict,linkhyperdict)
+  # Unused targets are nice to know
   checkmissingref("hyperlinks",targhyperdict,linkhyperdict)
+  checkmissingref("labels",labeldict,labelrefdict)
 
+  # Missing targets are a problem to be FIXED
+  checkmissingtarg("hyperlinks",targhyperdict,linkhyperdict)
   checkmissingtarg("labels",labeldict,labelrefdict)
-  checkmissingref("labels",labeldict,labelrefdict)
 
 # Perhaps these should be controlled by
 # the command line.
 debug   = "n"
-winpath = "n"
+
 def buildfilepaths(files,basetarg):
   outlist = []
   prefix = ""
@@ -851,10 +862,8 @@ def buildfilepaths(files,basetarg):
     prefix = ""
     if len(basetarg) > 0:
       prefix = basetarg
-    elif winpath == "y":
-      prefix = "..\\latexdoc\\"
     else:
-      prefix = "../latexdoc/"
+      prefix = os.path.join("..","latexdoc","")
     outlist += [prefix + f]
   return outlist
 def read_all_args():