From 0eeefdb4cc31feba24f95568803ab7799e77e401 Mon Sep 17 00:00:00 2001 From: Ron Brender Date: Fri, 20 May 2016 15:35:06 -0400 Subject: [PATCH] Incorporate changes as of the May 17 meeting. The corresponding .pdf is being distributed... Signed-off-by: Ron Brender --- dwarf5/latexdoc/attributesbytag.tex | 22 ++- dwarf5/latexdoc/changesummary.tex | 1 + dwarf5/latexdoc/datarepresentation.tex | 160 ++++++++++++++++-- dwarf5/latexdoc/debugsectionrelationships.tex | 24 +-- dwarf5/latexdoc/dwarf5.tex | 20 ++- dwarf5/latexdoc/dwarfnamecmds.tex | 17 +- dwarf5/latexdoc/generaldescription.tex | 16 +- dwarf5/latexdoc/introduction.tex | 3 + dwarf5/latexdoc/otherdebugginginformation.tex | 47 +++-- dwarf5/latexdoc/programscope.tex | 104 +++++++----- dwarf5/latexdoc/splitobjects.tex | 31 ++-- dwarf5/latexdoc/typeentries.tex | 2 + 12 files changed, 327 insertions(+), 120 deletions(-) diff --git a/dwarf5/latexdoc/attributesbytag.tex b/dwarf5/latexdoc/attributesbytag.tex index 2805f7e..a0352c5 100644 --- a/dwarf5/latexdoc/attributesbytag.tex +++ b/dwarf5/latexdoc/attributesbytag.tex @@ -199,8 +199,8 @@ For simplicity, this attribute is not explicitly shown. &\DWATaddrbase{} \\* &\DWATbasetypes{} \\* &\DWATcompdir{} \\* -&\DWATdwoid{} \\* -&\DWATdwoname{} \\* +\bbeb %\DWATdwoid{} \\* +\bbeb %\DWATdwoname{} \\* &\DWATentrypc{} \\* &\DWATidentifiercase{} \\* &\DWAThighpc{} \\* @@ -500,7 +500,7 @@ For simplicity, this attribute is not explicitly shown. &\DWATbasetypes{} \\* &\DWATcompdir{} \\* %\DWATdescription{} \\* -&\DWATdwoid{} \\* +\bbeb %&\DWATdwoid{} \\* &\DWATdwoname{} \\* &\DWATentrypc{} \\* &\DWATidentifiercase{} \\* @@ -596,6 +596,22 @@ For simplicity, this attribute is not explicitly shown. &\DWATname{} \\* &\DWATtype{} \\ +\hline +\bb +\DWTAGskeletonunit +&\DWATaddrbase{} \\* +&\DWATcompdir{} \\* +&\DWATdwoname{} \\* +&\DWAThighpc{} \\* +&\DWATlowpc{} \\* +&\DWATranges{} \\* +&\DWATrangesbase{} \\* +&\DWATstmtlist{} \\* +&\DWATstroffsetsbase{} \\* +&\DWATuseUTFeight{} +\eb +\\ + \hline \DWTAGstringtype &\livelink{chap:DECL}{DECL} \\* diff --git a/dwarf5/latexdoc/changesummary.tex b/dwarf5/latexdoc/changesummary.tex index 5a790c9..18543e4 100644 --- a/dwarf5/latexdoc/changesummary.tex +++ b/dwarf5/latexdoc/changesummary.tex @@ -15,6 +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 +5/19-20/2016 & 150331.1 (Add language RenderScript), 160108.1 (Unify unit headers) \\ 4/15-5/2/2016 & Remove change bars, Other miscellaneous editorial work \\ 3/4-7/2016 & Editorial work from 3/4/2016 editorial review \\ 2/8/2016 & More editorial work from 1/29/2016 editorial review \\ diff --git a/dwarf5/latexdoc/datarepresentation.tex b/dwarf5/latexdoc/datarepresentation.tex index 2007ff7..55958f6 100644 --- a/dwarf5/latexdoc/datarepresentation.tex +++ b/dwarf5/latexdoc/datarepresentation.tex @@ -289,12 +289,7 @@ file. This partition includes the following: \item The full compilation unit, in the \dotdebuginfodwo{} section. \begin{itemize} -\item -The full compilation unit entry includes a \DWATdwoid{} -attribute whose form and value is the same as that of the \DWATdwoid{} -attribute of the associated skeleton unit. - -\needlines{4} +\bbeb \item Attributes contained in the full compilation unit may refer to machine addresses indirectly using the \DWFORMaddrx{} @@ -396,6 +391,7 @@ produced during the compilation of an application.} application, and is given the same name with a \doublequote{\texttt{.dwp}} extension.\addtoindexx{\texttt{.dwp} file extension}} +\needlines{4} A DWARF package file is itself an object file, using the \addtoindexx{package files} \addtoindexx{DWARF package files} @@ -428,7 +424,9 @@ section. The DWARF package file also contains two index sections that provide a fast way to locate debug information by compilation -unit ID (\DWATdwoid) for compilation units, or by type +unit ID +\bbeb +for compilation units, or by type signature for type units: \begin{alltt} \dotdebugcuindex @@ -882,7 +880,7 @@ contribution may also be made to the section of the object file. Each such contribution consists of a \addtoindex{type unit} header -(see Section \refersec{datarep:typeunitheader}) +(see Section \refersec{datarep:typeunitheaders}) followed by a \DWTAGtypeunit{} entry, together with its children. @@ -925,10 +923,25 @@ enumeration are shown in Table \refersec{tab:unitheaderunitkindencodings}. \endlastfoot \DWUTcompileTARG~\ddag &0x01 \\ \DWUTtypeTARG~\ddag &0x02 \\ -\DWUTpartialTARG~\ddag &0x03 \\ \hline +\DWUTpartialTARG~\ddag &0x03 \\ +\bb +\DWUTskeletonTARG~\ddag &0x04 \\ +\DWUTsplitcompileTARG~\ddag &0x05 \\ +\DWUTsplittypeTARG~\ddag &0x06 \\ +\DWUTlouserTARG~\ddag &0x80 \\ +\DWUThiuserTARG~\ddag &\xff +\eb +\\ +\hline \end{longtable} \end{centering} +\bb +\textit{All unit headers in a compilation have the same size. +Some header types include padding bytes to achieve this.} +\eb + + \needlines{5} \subsubsection{Compilation and Partial Unit Headers} \label{datarep:compilationunitheader} @@ -990,11 +1003,100 @@ the \thirtytwobitdwarfformat, this is a 4-byte unsigned length; in the \sixtyfourbitdwarfformat, this is an 8-byte unsigned length (see Section \refersec{datarep:32bitand64bitdwarfformats}). +\bb +\item \HFNunitpaddingONE{} (8 bytes) \\ +Reserved to DWARF (must be zero). + +\needlines{4} +\item \HFNunitpaddingTWO{} (4 or 8 bytes) \\ +Reserved to DWARF (must be zero). In the \thirtytwobitdwarfformat, +this is 4 bytes in length; in the \sixtyfourbitdwarfformat this +is 8 bytes in length. +\eb \end{enumerate} \needlines{8} -\subsubsection{Type Unit Header} -\label{datarep:typeunitheader} +\bb +\subsubsection{Skeleton and Split Compilation Unit Headers} +\label{datarep:skeletonandfullcompilationunitheaders} +\begin{enumerate}[1. ] + +\item \texttt{unit\_length} (\livelink{datarep:initiallengthvalues}{initial length}) \\ +\addttindexx{unit\_length} +A 4-byte or 12-byte +\addtoindexx{initial length} +unsigned integer representing the length +of the \dotdebuginfo{} +contribution for that compilation unit, +not including the length field itself. In the \thirtytwobitdwarfformat, +this is a 4-byte unsigned integer (which must be less +than \xfffffffzero); in the \sixtyfourbitdwarfformat, this consists +of the 4-byte value \wffffffff followed by an 8-byte unsigned +integer that gives the actual length +(see Section \refersec{datarep:32bitand64bitdwarfformats}). + +\item \texttt{version} (\HFTuhalf) \\ +\addttindexx{version} +\addtoindexx{version number!compilation unit} +A 2-byte unsigned integer representing the version of the +DWARF information for the compilation unit. + +The value in this field is \versiondotdebuginfo. + +\textit{See also Appendix \refersec{app:dwarfsectionversionnumbersinformative} +for a summary of all version numbers that apply to DWARF sections.} + +\needlines{4} +\item \texttt{unit\_type} (\HFTubyte) \\ +\addttindexx{unit\_type} +A 1-byte unsigned integer identifying this unit as a compilation unit. +The value of this field is +\DWUTskeleton{} for a skeleton compilation unit or +\DWUTsplitcompile{} for a split compilation unit +(see Section \refersec{chap:skeletoncompilationunitentries}). + +\textit{This field is new in \DWARFVersionV.} + +\needlines{4} +\item \texttt{address\_size} (\HFTubyte) \\ +\addttindexx{address\_size} +A 1-byte unsigned integer representing the size in bytes of +an address on the target architecture. If the system uses +\addtoindexx{address space!segmented} +segmented addressing, this value represents the size of the +offset portion of an address. + +\item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\ +A +\addtoindexx{section offset!in .debug\_info header} +4-byte or 8-byte unsigned offset into the +\dotdebugabbrev{} +section. This offset associates the compilation unit with a +particular set of debugging information entry abbreviations. In +the \thirtytwobitdwarfformat, this is a 4-byte unsigned length; +in the \sixtyfourbitdwarfformat, this is an 8-byte unsigned length +(see Section \refersec{datarep:32bitand64bitdwarfformats}). + +\needlines{6} +\item \HFNdwoid{} (unit ID) \\ +An 8-byte implementation-defined integer constant value, +known as the compilation unit ID, that provides +unique identification of a skeleton compilation +unit and its associated split compilation unit in +the object file named in the \DWATdwoname{} attribute +of the skeleton compilation. + +\needlines{4} +\item \HFNunitpaddingTWO{} (4 or 8 bytes) \\ +Reserved to DWARF (must be zero). In the \thirtytwobitdwarfformat, +this is 4 bytes in length; in the \sixtyfourbitdwarfformat this +is 8 bytes in length. +\eb +\end{enumerate} + +\needlines{8} +\subsubsection{Type Unit Headers} +\label{datarep:typeunitheaders} The header for the series of debugging information entries contributing to the description of a type that has been placed in its own \addtoindex{type unit}, within the @@ -1026,8 +1128,15 @@ The value in this field is \versiondotdebuginfo. \item \texttt{unit\_type} (\HFTubyte) \\ \addttindexx{unit\_type} A 1-byte unsigned integer identifying this unit as a type unit. -The value of this field is \DWUTtype{} for a type unit -(see Section \refersec{chap:typeunitentries}). +The value of this field is \DWUTtype{} for a +\bb +non-split +\eb +type unit +(see Section \refersec{chap:typeunitentries}) +\bb +or \DWUTsplittype{} for a split type unit. +\eb \textit{This field is new in \DWARFVersionV.} @@ -1042,6 +1151,7 @@ an address on the target architecture. If the system uses segmented addressing, this value represents the size of the offset portion of an address. +\needlines{6} \item \HFNdebugabbrevoffset{} (\livelink{datarep:sectionoffsetlength}{section offset}) \\ A \addtoindexx{section offset!in .debug\_info header} @@ -1066,7 +1176,7 @@ unit. the primary type contained in this \addtoindex{type unit} uses this value.} -\needlines{4} +\needlines{8} \item \texttt{type\_offset} (\livelink{datarep:sectionoffsetlength}{section offset}) \\ \addttindexx{type\_offset} A 4-byte or 8-byte unsigned offset @@ -1195,6 +1305,11 @@ Table \refersec{tab:tagencodings}. \DWTAGunspecifiedtype&0x3b \\ \DWTAGpartialunit&0x3c \\ \DWTAGimportedunit&0x3d \\ +\bb +\textit{Reserved}&0x3e\footnote{Code 0x3e is reserved to allow backward compatible support of the +DW\_TAG\_mutable\_type DIE that was defined (only) in \DWARFVersionIII.} +\eb +\\ \DWTAGcondition&\xiiif \\ \DWTAGsharedtype&0x40 \\ \DWTAGtypeunit & 0x41 \\ @@ -1206,6 +1321,10 @@ Table \refersec{tab:tagencodings}. \DWTAGatomictype~\ddag & 0x47 \\ \DWTAGcallsite~\ddag & 0x48 \\ \DWTAGcallsiteparameter~\ddag & 0x49 \\ +\bb +\DWTAGskeletonunit~\ddag & 0x4a +\eb +\\ \DWTAGlouser&0x4080 \\ \DWTAGhiuser&\xffff \\ \end{longtable} @@ -1559,9 +1678,10 @@ Table \referfol{tab:attributeencodings}. \DWATrangesbase~\ddag&0x74& \livelinki{chap:classrangelistptr}{rangelistptr}{rangelistptr class} \addtoindexx{ranges base!encoding} \\ -\DWATdwoid~\ddag &0x75& - \livelink{chap:classconstant}{constant} - \addtoindexx{split DWARF object file id!encoding} \\ +\bb +\textit{Reserved} &0x75& \textit{Unused} +\eb +\\ \DWATdwoname~\ddag &0x76& \livelink{chap:classstring}{string} \addtoindexx{split DWARF object file name!encoding} \\ @@ -1569,7 +1689,7 @@ Table \referfol{tab:attributeencodings}. \livelink{chap:classflag}{flag} \\ \DWATrvaluereference~\ddag &0x78& \livelink{chap:classflag}{flag} \\ -\DWATmacros~\ddag &0x79&\livelink{chap:classmacptr}{macptr} +\DWATmacros~\ddag &0x79&\livelink{chap:classmacptr}{macptr} \addtoindexx{macro information attribute} \\ \DWATcallallcalls~\ddag &0x7a&\CLASSflag \addtoindexx{all calls summary attribute} \\ @@ -2691,6 +2811,10 @@ defined language. \DWLANGCplusplusfourteen{}~\ddag &0x0021 &0 \addtoindexx{C++14 (ISO)} \\ \DWLANGFortranzerothree{}~\ddag &0x0022 &1 \addtoindexx{Fortran:2004 (ISO)} \\ \DWLANGFortranzeroeight{}~\ddag &0x0023 &1 \addtoindexx{Fortran:2010 (ISO)} \\ +\bb +\DWLANGRenderScript{}~\ddag &0x0024 &0 \addtoindexx{RenderScript Kernel Language} +\eb +\\ \DWLANGlouser{} &0x8000 & \\ \DWLANGhiuser{} &\xffff & \\ diff --git a/dwarf5/latexdoc/debugsectionrelationships.tex b/dwarf5/latexdoc/debugsectionrelationships.tex index 38492df..61f9fe7 100644 --- a/dwarf5/latexdoc/debugsectionrelationships.tex +++ b/dwarf5/latexdoc/debugsectionrelationships.tex @@ -428,9 +428,15 @@ The circled (s) connects to the circled The \texttt{debug\_info\_offset} field in the header is the offset in the \dotdebuginfo{} section of the corresponding compilation unit header of the skeleton \dotdebuginfo{} section -(not the compilation unit entry). The \DWATdwoid{} and -\DWATdwoname{} attributes in the \dotdebuginfo{} skeleton -connect the ranges to the full compilation unit in \dotdebuginfodwo. +(not the compilation unit entry). The +\bb +\DWATdwoname{} attribute +\eb +in the \dotdebuginfo{} skeleton +\bb +connects +\eb +the ranges to the full compilation unit in \dotdebuginfodwo. \itembfnl{(b) \dotdebugnames{} to \dotdebuginfo} The \dotdebugnames{} section offsets lists provide an offset @@ -457,13 +463,11 @@ whose value is an offset in the \dotdebugstr{} section of the corresponding string. \itembfnl{(did) \dotdebuginfo{} to \dotdebuginfodwo} -The \DWATdwoname{} and \DWATdwoid{} are the file name -and hash which identify the file with -the \texttt{.dwo} data. Both \dotdebuginfo{} and -\dotdebuginfodwo{} compilation units should contain -\DWATdwoid{} so the two can be matched. \DWATdwoname{} -is only needed in the \dotdebuginfo{} -skeleton compilation unit. +The \DWATdwoname{} +\bb +attribute in a skeleton unit identifies the file containing +the corresponding \texttt{.dwo} (split) data. +\eb \itembfnl{(do) \dotdebuginfodwo{} to \dotdebugstrdwo} Attribute values of class string may have form diff --git a/dwarf5/latexdoc/dwarf5.tex b/dwarf5/latexdoc/dwarf5.tex index eca4080..ad87abb 100644 --- a/dwarf5/latexdoc/dwarf5.tex +++ b/dwarf5/latexdoc/dwarf5.tex @@ -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}{May 2, 2016} +\newcommand{\docdate}{May 20, 2016} % \usepackage{ifthen} \newcommand{\ifthen}[2]{\ifthenelse{#1}{#2}{}} @@ -144,13 +144,17 @@ escapeinside={\%*}{*)} % if you want to add a comment within your code % For index entries. The tt-variant of each pair is designed to % allow a word to appear in tt font in the main test and the index -% but to collate in the index in its non-tt order. (LaTex normally -% sorts all tt words before all non-tt words.) +% but to collate in the index in its non-tt order. Similarly for +% the it-variant using italics font. +% (LaTex normally % sorts all tt words before all non-tt words.) \newcommand{\addtoindex}[1]{#1\index{#1}} +\newcommand{\additindex}[1]{\textit{#1}\index{#1@\textit{#1}}} \newcommand{\addttindex}[1]{\texttt{#1}\index{#1@\texttt{#1}}} \newcommand{\addtoindexi}[2]{#1\index{#2}} +\newcommand{\additindexi}[2]{\textit{#1}\index{#2@\textit{#2}}} \newcommand{\addttindexi}[2]{\texttt{#1}\index{#2@\texttt{#2}}} \newcommand{\addtoindexx}[1]{\index{#1}} +\newcommand{\additindexx}[1]{\index{#1@\textit{#1}}} \newcommand{\addttindexx}[1]{\index{#1@\texttt{#1}}} % Quote commands that avoid need for inline UTF-8 in these sources @@ -353,11 +357,11 @@ escapeinside={\%*}{*)} % if you want to add a comment within your code \uselinenos\include{introduction} %\emptypage \uselinenos\include{generaldescription} \emptypage -\uselinenos\include{programscope} \emptypage +\uselinenos\include{programscope} %\emptypage \uselinenos\include{dataobject} \emptypage \uselinenos\include{typeentries} \emptypage -\uselinenos\include{otherdebugginginformation} \emptypage -\uselinenos\include{datarepresentation} %\emptypage +\uselinenos\include{otherdebugginginformation} %\emptypage +\uselinenos\include{datarepresentation} \emptypage % The \appendix command toggles us into appendix chapters \appendix @@ -365,9 +369,9 @@ escapeinside={\%*}{*)} % if you want to add a comment within your code \uselinenos\include{attributesbytag} %\emptypage \uselinenos\include{debugsectionrelationships} \emptypage \uselinenos\include{encodingdecoding} \emptypage -\uselinenos\include{examples} \emptypage +\uselinenos\include{examples} %\emptypage \uselinenos\include{compression} \emptypage -\uselinenos\include{splitobjects} \emptypage +\uselinenos\include{splitobjects} \emptypage \uselinenos\include{sectionversionnumbers} \emptypage \nolinenumbers \include{gnulicense} \emptypage diff --git a/dwarf5/latexdoc/dwarfnamecmds.tex b/dwarf5/latexdoc/dwarfnamecmds.tex index 71fdccf..75a6757 100644 --- a/dwarf5/latexdoc/dwarfnamecmds.tex +++ b/dwarf5/latexdoc/dwarfnamecmds.tex @@ -97,7 +97,7 @@ \newdwfnamecommands{DWATdiscr}{DW\_AT\_discr} \newdwfnamecommands{DWATdiscrlist}{DW\_AT\_discr\_list} \newdwfnamecommands{DWATdiscrvalue}{DW\_AT\_discr\_value} -\newdwfnamecommands{DWATdwoid}{DW\_AT\_dwo\_id} +%newdwfnamecommands{DWATdwoid}{DW\_AT\_dwo\_id} \newdwfnamecommands{DWATdwoname}{DW\_AT\_dwo\_name} % \newdwfnamecommands{DWATelemental}{DW\_AT\_elemental} @@ -371,6 +371,7 @@ \newdwfnamecommands{DWLANGPascaleightythree}{DW\_LANG\_Pascal83} \newdwfnamecommands{DWLANGPLI}{DW\_LANG\_PLI} \newdwfnamecommands{DWLANGPython}{DW\_LANG\_Python} +\newdwfnamecommands{DWLANGRenderScript}{DW\_LANG\_RenderScript} \newdwfnamecommands{DWLANGRust}{DW\_LANG\_Rust} \newdwfnamecommands{DWLANGSwift}{DW\_LANG\_Swift} \newdwfnamecommands{DWLANGUPC}{DW\_LANG\_UPC} @@ -623,6 +624,7 @@ \newdwfnamecommands{DWTAGrvaluereferencetype}{DW\_TAG\_rvalue\_reference\_type} \newdwfnamecommands{DWTAGsettype}{DW\_TAG\_set\_type} \newdwfnamecommands{DWTAGsharedtype}{DW\_TAG\_shared\_type} +\newdwfnamecommands{DWTAGskeletonunit}{DW\_TAG\_skeleton\_unit} \newdwfnamecommands{DWTAGstringtype}{DW\_TAG\_string\_type} \newdwfnamecommands{DWTAGstructuretype}{DW\_TAG\_structure\_type} \newdwfnamecommands{DWTAGsubprogram}{DW\_TAG\_subprogram} @@ -649,10 +651,12 @@ \newdwfnamecommands{DWUTcompile}{DW\_UT\_compile} \newdwfnamecommands{DWUTtype}{DW\_UT\_type} \newdwfnamecommands{DWUTpartial}{DW\_UT\_partial} -\newdwfnamecommands{DWUTskeleton}{DW\_UT\_skeleton} % keep? -\newdwfnamecommands{DWUTsplitcompile}{DW\_UT\_split\_compile} % keep? -\newdwfnamecommands{DWUTsplittype}{DW\_UT\_split\_type} % keep? -\newdwfnamecommands{DWUTsplitpartial}{DW\_UT\_split\_partial} % keep? +\newdwfnamecommands{DWUTskeleton}{DW\_UT\_skeleton} +\newdwfnamecommands{DWUTsplitcompile}{DW\_UT\_split\_compile} +\newdwfnamecommands{DWUTsplittype}{DW\_UT\_split\_type} +%\newdwfnamecommands{DWUTsplitpartial}{DW\_UT\_split\_partial} % keep? +\newdwfnamecommands{DWUTlouser}{DW\_UT\_lo\_user} +\newdwfnamecommands{DWUThiuser}{DW\_UT\_hi\_user} % % DW_VIRTUALITY % @@ -775,6 +779,7 @@ \newcommand{\HFNdirectoryentryformat} {\addttindex{directory\_entry\_format}} \newcommand{\HFNdirectoriescount} {\addttindex{directories\_count}} \newcommand{\HFNdirectories} {\addttindex{directories}} +\newcommand{\HFNdwoid} {\addttindex{dwo\_id}} \newcommand{\HFNfilenameentryformatcount} {\addttindex{file\_name\_entry\_format\_count}} \newcommand{\HFNfilenameentryformat} {\addttindex{file\_name\_entry\_format}} \newcommand{\HFNfilenamescount} {\addttindex{file\_names\_count}} @@ -800,6 +805,8 @@ \newcommand{\HFNtypeoffset} {\addttindex{type\_offset}} \newcommand{\HFNtypesignature} {\addttindex{type\_signature}} \newcommand{\HFNunitlength} {\addttindex{unit\_length}} +\newcommand{\HFNunitpaddingONE} {\additindex{padding1}} +\newcommand{\HFNunitpaddingTWO} {\additindex{padding2}} \newcommand{\HFNunittype} {\addttindex{unit\_type}} \newcommand{\HFNversion} {\addttindex{version}} % diff --git a/dwarf5/latexdoc/generaldescription.tex b/dwarf5/latexdoc/generaldescription.tex index cc087e3..11f1824 100644 --- a/dwarf5/latexdoc/generaldescription.tex +++ b/dwarf5/latexdoc/generaldescription.tex @@ -73,6 +73,9 @@ described in Chapters 3, 4 and 5. \DWTAGrvaluereferencetype, \DWTAGsettype, \DWTAGsharedtype, +\bb +\DWTAGskeletonunit, +\eb \DWTAGstringtype, \DWTAGstructuretype, \DWTAGsubprogram, @@ -451,10 +454,7 @@ The attributes are listed in Table \referfol{tab:attributenames}. &\livelinki{chap:DWATdiscrvaluediscriminantvalue} {Discriminant value} {discriminant value} \\ -\DWATdwoidTARG -&\livelinki{chap:DWATdwoidforunit} - {Signature for compilation unit} - {split DWARF object file!unit ID} \\ +\bbeb \DWATdwonameTARG &\livelinki{chap:DWATdwonameforunit} {Name of split DWARF object file} @@ -1686,7 +1686,10 @@ subprogram, record values needed by \DWOPentryvalueNAME{} expressions within the subprogram, and then continue; when evaluating \DWOPentryvalueNAME{}, the consumer would use these recorded values rather than the current values. Or, when evaluating \DWOPentryvalueNAME{}, the consumer could -"virtually unwind" using the Call Frame Information +\bb +virtually unwind +\eb +using the Call Frame Information (see Section \refersec{chap:callframeinformation}) to recover register values that might have been clobbered since the subprogram entry point.} @@ -2742,6 +2745,7 @@ offset within the \dotdebugranges{} section for the compilation unit. The offset given by the \DWATranges{} attribute is relative to that base. +\needlines{4} The \definitionx{applicable base address} of a \addtoindex{range list} entry is determined by the closest preceding base address selection entry in the same range list (see @@ -2866,7 +2870,7 @@ as the lower bound of an array) that is an integer value, where the value may be known during compilation or may be computed dynamically during execution. -\needlines{5} +\needlines{8} The value of these attributes is determined based on the class as follows: \begin{itemize} diff --git a/dwarf5/latexdoc/introduction.tex b/dwarf5/latexdoc/introduction.tex index 6a595d8..dbbc749 100644 --- a/dwarf5/latexdoc/introduction.tex +++ b/dwarf5/latexdoc/introduction.tex @@ -212,6 +212,9 @@ DWARF describes the source to object translation explicitly rather than using common practice or convention as an implicit understanding between producer and consumer. For example, where other debugging formats assume that a debugger knows how to +\bb +virtually +\eb unwind the stack, moving from one stack frame to the next using implicit knowledge about the architecture or operating system, DWARF makes this explicit in the Call Frame Information description. diff --git a/dwarf5/latexdoc/otherdebugginginformation.tex b/dwarf5/latexdoc/otherdebugginginformation.tex index 05b0287..6e072c2 100644 --- a/dwarf5/latexdoc/otherdebugginginformation.tex +++ b/dwarf5/latexdoc/otherdebugginginformation.tex @@ -1391,7 +1391,8 @@ goals:} \addttindexx{directory\_entry\_format\_count} A count of the number of entries that occur in the following \addttindex{directory\_entry\_format} field. - + +\needlines{8} \item \texttt{directory\_entry\_format} (sequence of ULEB128 pairs) \\ \addttindexx{directory\_entry\_format} A sequence of directory entry format descriptions. @@ -1454,6 +1455,7 @@ occur in the following \addttindex{file\_name\_entry\_format} field. If this field is zero, then the \addttindex{file\_names\_count} field (see below) must also be zero. +\needlines{6} \item \texttt{file\_name\_entry\_format} (sequence of ULEB128 pairs) \\ \addttindexx{file\_name\_entry\_format} A sequence of file entry format descriptions. @@ -1504,6 +1506,7 @@ share a single copy of the current file name string.} \end{enumerate} +\needlines{8} \subsubsection{Standard Content Descriptions} \label{chap:standardcontentdescriptions} DWARF-defined content type codes are used to indicate @@ -2263,6 +2266,7 @@ similarly, \DWMACROimport{} entries refer to the \needlines{6} \section{Call Frame Information} \label{chap:callframeinformation} +\addtoindexx{unwind|see{virtual unwind}}\addtoindexx{virtual unwind} \textit{Debuggers often need to be able to view and modify the state of any subroutine activation that is @@ -2294,7 +2298,7 @@ across a call. If a callee wishes to use such a register, it saves the value that the register had at entry time in its call frame and restores it on exit. The code that allocates space on the call frame stack and performs the save operation is -called the subroutine\textquoteright s \addtoindex{prologue}, and the code that performs +called the subroutine\textquoteright{s} \addtoindex{prologue}, and the code that performs the restore operation and deallocates the frame is called its \addtoindex{epilogue}. Typically, the \addtoindex{prologue} code is physically at the @@ -2303,19 +2307,30 @@ beginning of a subroutine and the \textit{To be able to view or modify an activation that is not on the top of the call frame stack, the debugger must -\doublequote{virtually unwind} the stack of activations until -it finds the activation of interest. A debugger unwinds +\bb +virtually unwind +\eb +the stack of activations until +it finds the activation of interest. A debugger +\bb +virtually +\eb +unwinds a stack in steps. Starting with the current activation it virtually restores any registers that were preserved by the -current activation and computes the predecessor\textquoteright s CFA and +current activation and computes the predecessor\textquoteright{s} CFA and code location. This has the logical effect of returning from 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 +\textit{The +\bb +virtual unwind +\eb +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:} @@ -2514,7 +2529,11 @@ If there is no augmentation, this value is a zero byte. \needlines{5} \textit{The augmentation string allows users to indicate that there is additional target\dash specific information in the CIE or FDE -which is needed to unwind a stack frame. For example, this +which is needed to +\bb +virtually +\eb +unwind a stack frame. For example, this might be information about dynamically allocated data which needs to be freed on exit from the routine.} @@ -2979,7 +2998,11 @@ Appendix \refersec{app:callframeinformationexample}.} \subsection{Call Frame Calling Address} \label{chap:callframecallingaddress} -\textit{When unwinding frames, consumers frequently wish to obtain the +\textit{When +\bb +virtually +\eb +unwinding frames, consumers frequently wish to obtain the address of the instruction which called a subroutine. This information is not always provided. Typically, however, one of the registers in the virtual unwind table is the @@ -2999,7 +3022,11 @@ context of the 'return address' might be on a different line, in a different lexical \livelink{chap:lexicalblock}{block}, or past the end of the calling subroutine. If a consumer were to assume that it was in the -same context as the calling address, the unwind might fail.} +same context as the calling address, the +\bb +virtual +\eb +unwind might fail.} \needlines{5} \textit{For architectures with constant-length instructions where diff --git a/dwarf5/latexdoc/programscope.tex b/dwarf5/latexdoc/programscope.tex index 0796d71..fa1f2b1 100644 --- a/dwarf5/latexdoc/programscope.tex +++ b/dwarf5/latexdoc/programscope.tex @@ -233,6 +233,10 @@ in Table \refersec{tab:languagenames}. \DWLANGPascaleightythreeTARG & ISO Pascal:1983 \addtoindexx{Pascal:1983 (ISO)} \\ \DWLANGPLITARG{}~\dag & ANSI PL/I:1976 \addtoindexx{PL/I:1976 (ANSI)} \\ \DWLANGPythonTARG{}~\dag & \addtoindex{Python} \\ +\bb +\DWLANGRenderScriptTARG~\dag & \addtoindex{RenderScript Kernal Language} +\eb +\\ \DWLANGRustTARG{}~\dag & \addtoindex{Rust} \\ \DWLANGSwiftTARG{} & \addtoindex{Swift} \\ @@ -451,8 +455,12 @@ of that compilation unit is not valid. When generating a \splitDWARFobjectfile{} (see Section \refersec{datarep:splitdwarfobjectfiles}), the compilation unit in the \dotdebuginfo{} section is a "skeleton" -compilation unit with the tag \DWTAGcompileunit, which contains -\DWATdwoname{} and \DWATdwoid{} attributes as well as a subset of the +compilation unit with the tag +\bb +\DWTAGskeletonunitTARG, which contains a +\DWATdwoname{} attribute +\eb +as well as a subset of the attributes of a full or partial compilation unit. In general, it contains those attributes that are necessary for the consumer to locate the object file where the split full compilation unit @@ -462,8 +470,10 @@ addresses in the program. A skeleton compilation unit has no children. -A skeleton compilation unit has \DWATdwoname{} and -\DWATdwoid{} attributes: +A skeleton compilation unit has +\bb +a \DWATdwoname{} attribute: +\eb \begin{enumerate}[1. ] @@ -476,22 +486,20 @@ path name (relative to the value of the \DWATcompdir{} attribute, see below) of the object file that contains the full compilation unit. -\item \livetarg{chap:DWATdwoidforunit}{} -A \DWATdwoidDEFN{} attribute\addtoindexx{unit identification attribute} -whose implementation-defined integer constant value, -known as the \CUsignature, -provides unique identification of this compilation unit -as well as the associated split compilation unit in the -object file named in the \DWATdwoname{} -attribute. For simplicity, the \DWATdwoidNAME{} attributes -in the skeleton compilation unit and the corresponding -split full compilation unit -(see Section \refersec{chap:splitfullcompilationunitentries}) -must use the same form to encode this identification value. - -\textit{The means of determining a \CUsignature{} does not -need to be similar or related to the means of determining a -\TUsignature.} +\bb +The value in the \HFNdwoid{} field of the unit header for +this unit is the same as the value in the \HFNdwoid{} field +of the unit header of the corresponding full compilation +unit (see Section \refersec{datarep:unitheaders}). + +\textit{The means of determining a compilation unit ID does +not need to be similar or related to the means of +determining a \TUsignature. However, it should +be suitable for detecting file version skew or other +kinds of mismatched files and for looking up a full +split unit in a DWARF package file +(see Section \refersec{datarep:dwarfpackagefiles}).} +\eb \end{enumerate} @@ -499,7 +507,7 @@ A skeleton compilation unit may have additional attributes, which are the same as for conventional compilation unit entries except as noted, from among the following: \begin{enumerate}[1. ] -\addtocounter{enumi}{2} +\addtocounter{enumi}{1} \item Either a \DWATlowpc{} and \DWAThighpc{} pair of attributes or a \DWATranges{} attribute. \item A \DWATstmtlist{} attribute. @@ -529,9 +537,8 @@ should be placed in the split full compilation unit (see \refersec{chap:splitfullcompilationunitentries}). The attributes provided by the skeleton compilation unit entry do not need to be repeated in the full compilation -unit entry, except for \DWATdwoid, which should appear in -both entries so that the consumer can verify that it has -found the correct object file. +unit entry. +\bbeb \textit{The \DWATaddrbase{}, \DWATrangesbase{} and \DWATstroffsetsbase{} attributes provide context that may be @@ -550,27 +557,13 @@ It is very similar to a conventional full compilation unit but is logically paired with a specific skeleton compilation unit while being physically separate. -A split full compilation unit has a \DWATdwoid{} attribute: -\begin{enumerate}[1. ] -\item -A \DWATdwoidDEFN{} attribute\addtoindexx{unit identification attribute} -whose implementation-defined integer constant value, -known as the \CUsignature, -provides unique identification of this compilation unit -as well as the associated skeleton compilation unit. -For simplicity, the \DWATdwoidNAME{} attributes in the -split compilation unit and the associated skeleton -compilation unit must use the same form to encode the -identification value. - -\end{enumerate} - -\needlines{4} -A split full compilation unit may also have additional attributes, +A split full compilation unit +\bb +may have the following attributes, which are the same as for conventional compilation unit entries -except as noted, from among the following: +except as noted: +\eb \begin{enumerate}[1. ] -\addtocounter{enumi}{1} \item A \DWATname{} attribute. \item A \DWATlanguage{} attribute. \item A \DWATmacros{} attribute. @@ -717,6 +710,7 @@ left in the main compilation unit.} entities into a single entity and to manage the names of those entities.} +\needlines{8} \subsection{Module Entries} \label{chap:moduleentries} \textit{Several languages have the concept of a \doublequote{module.} @@ -882,6 +876,7 @@ making accessible in a given unit certain declarations that occur in a different module or scope. An imported declaration may sometimes be given another name.} +\needlines{6} An imported declaration is represented by one or \addtoindexx{imported declaration entry} more debugging information entries with the @@ -1613,6 +1608,7 @@ nested within another abstract instance tree, the entries in the tree are not considered to be entries in the outer abstract instance tree. +\needlines{6} Each abstract instance root is either part of a larger \addtoindexx{abstract instance!root} tree (which gives a context for the root) or @@ -2065,7 +2061,11 @@ call is executed. After the called subprogram has been entered, these registers and memory locations might have been modified. In order to recover the values that existed at the point of the call (to allow evaluation of the DWARF expression for the actual parameter), a debugger -may "virtually unwind" the subprogram activation +may +\bb +virtually unwind +\eb +the subprogram activation (see Section \refersec{chap:callframeinformation}). Any register or memory location that cannot be recovered is referred to as "clobbered by the call."} @@ -2081,7 +2081,11 @@ location for use by the callee. A \textit{tail call} uses a jump-like instruction which transfers control to the start of some subprogram, but there is no call site location address to preserve -(and thus none is available using the unwind information). +(and thus none is available using the +\bb +virtual +\eb +unwind information). \item A \textit{tail recursion call} is a call @@ -2231,7 +2235,10 @@ which is a DWARF expression which when evaluated yields the value of the parameter at the time of the call. \textit{The expression should not use registers or memory -locations that might be clobbered by the call, as it might be evaluated after +locations that might be clobbered by the call, as it might be evaluated after +\bb +virtually +\eb unwinding from the called function back to the caller. If it is not possible to avoid registers or memory locations that might be clobbered by the call in the expression, then the \DWATcallvalueNAME{} attribute should @@ -2257,7 +2264,10 @@ describes where the referenced value lives during the call. If it is just \DWOPpushobjectaddress{}, it may be left out. The \DWATcalldatavalueNAME{} attribute describes the value in that location. The expression should not use registers or memory -locations that might be clobbered by the call, as it might be evaluated after +locations that might be clobbered by the call, as it might be evaluated after +\bb +virtually +\eb unwinding from the called function back to the caller. \needlines{4} diff --git a/dwarf5/latexdoc/splitobjects.tex b/dwarf5/latexdoc/splitobjects.tex index 25bddd9..003efcd 100644 --- a/dwarf5/latexdoc/splitobjects.tex +++ b/dwarf5/latexdoc/splitobjects.tex @@ -161,7 +161,7 @@ may have the following attributes: \DWATaddrbase{}, \DWATcompdir{}, \DWATdwoname{}, -\DWATdwoid{}, +\bbeb %\DWATdwoid{}, \DWAThighpc{}, \DWATlowpc{}, \DWATranges{}, @@ -172,12 +172,14 @@ may have the following attributes: All other attributes of the compilation unit DIE are moved to the full DIE in the \dotdebuginfodwo{} section. -The \DWATdwoid{} attribute is present -in both the skeleton DIE and the full DIE, so that a consumer + +\bb +The \HFNdwoid{} field is present in headers of the skeleton DIE +and the header of the full DIE, so that a consumer can verify a match. +\eb \needlines{4} - Relocations are neither necessary nor useful in \texttt{.dwo} files, because the \texttt{.dwo} files contain only debugging information that does not need to be @@ -229,8 +231,8 @@ kinds. \hline \DWATcompdir & \chkmk & & \chkmk & & \\ \hline -\DWATdwoid & & & \chkmk & \chkmk & \\ -\hline +\bbeb %\DWATdwoid & & & \chkmk & \chkmk & \\ +%\hline \DWATdwoname & & & \chkmk & & \\ \hline \DWATentrypc & \chkmk & & & \chkmk & \\ @@ -422,10 +424,9 @@ Figure \referfol{fig:splitdwafexampleskeletondwarfdescription}. \begin{dwflisting} \begin{alltt} - \DWTAGcompileunit + \DWTAGskeletonunit \DWATcompdir: (reference to directory name in .debug_str) \DWATdwoname: (reference to "demo1.dwo" in .debug_str) - \DWATdwoid: 0x44e413b8a2d1b8f \DWATaddrbase: (reference to .debug_addr section) \DWATrangesbase: (reference to range list in .debug_ranges section) \DWATranges: (offset of range list in .debug_ranges section) @@ -443,8 +444,12 @@ location of the corresponding \splitDWARFobjectfile{} that contains the full debug information; that file is normally expected to be in the same directory as the object file itself. -The \DWATdwoid{} attribute provides a hash of the debug -information contained in the \splitDWARFobjectfile. This hash serves +The +\bb +\HFNdwoid{} field in the header of the skeleton unit provides +an ID or key for the debug information contained in the +DWARF object file. This ID serves +\eb two purposes: it can be used to verify that the debug information in the \splitDWARFobjectfile{} matches the information in the object file, and it can be used to find the debug information in a DWARF @@ -578,7 +583,6 @@ excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}. \DWATlanguage: \DWLANGCplusplus \DWATname [\DWFORMstrx]: (slot 7) "demo1.cc" \DWATcompdir [\DWFORMstrx]: (slot 4) (directory name) - \DWATdwoid [\DWFORMdataeight]: 0x44e413b8a2d1b8f 1$: \DWTAGclasstype \DWATname [\DWFORMstrx]: (slot 12) "Point" \DWATsignature [\DWFORMrefsigeight]: 0x2f33248f03ff18ab @@ -588,7 +592,7 @@ excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}. \DWATname [\DWFORMstrx]: (slot 12) "Point" \DWATdeclfile: 1 \DWATdeclline: 5 - \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff" + \DWATlinkagename [\DWFORMstrx]: (slot 16) "_ZN5PointC4Eff" \DWATaccessibility: \DWACCESSpublic \DWATdeclaration: true ... @@ -602,7 +606,8 @@ excerpts from the \dotdebuginfodwo{} section for \texttt{demo1.dwo}. \DWATname [\DWFORMstrx]: (slot 0) "contains" \DWATdeclfile: 1 \DWATdeclline: 28 - \DWATlinkagename [\DWFORMstrx: (slot 8) "_ZNK3Box8containsERK5Point" + \DWATlinkagename [\DWFORMstrx: (slot 8) + "_ZNK3Box8containsERK5Point" \DWATtype: (reference to 7$) \DWATaccessibility: \DWACCESSpublic \DWATdeclaration: true diff --git a/dwarf5/latexdoc/typeentries.tex b/dwarf5/latexdoc/typeentries.tex index 7a4cbb3..5c98b13 100644 --- a/dwarf5/latexdoc/typeentries.tex +++ b/dwarf5/latexdoc/typeentries.tex @@ -1631,6 +1631,7 @@ Each enumerator entry also has a whose value is the actual numeric value of the enumerator as represented on the target system. +\needlines{4} If the enumeration type occurs as the description of a \addtoindexx{enumeration type entry!as array dimension} dimension of an array type, and the stride for that @@ -2017,6 +2018,7 @@ whose value is a address of the member of the class to which the pointer to member entry points. +\needlines{4} \textit{The method used to find the address of a given member of a class or structure is common to any instance of that class or structure and to any instance of the pointer or member -- 2.17.1