.pdf is being distributed...
Signed-off-by: Ron Brender <ron.brender@gmail.com>
&\DWATaddrbase{} \\*
&\DWATbasetypes{} \\*
&\DWATcompdir{} \\*
-&\DWATdwoid{} \\*
-&\DWATdwoname{} \\*
+\bbeb %\DWATdwoid{} \\*
+\bbeb %\DWATdwoname{} \\*
&\DWATentrypc{} \\*
&\DWATidentifiercase{} \\*
&\DWAThighpc{} \\*
&\DWATbasetypes{} \\*
&\DWATcompdir{} \\*
%\DWATdescription{} \\*
-&\DWATdwoid{} \\*
+\bbeb %&\DWATdwoid{} \\*
&\DWATdwoname{} \\*
&\DWATentrypc{} \\*
&\DWATidentifiercase{} \\*
&\DWATname{} \\*
&\DWATtype{} \\
+\hline
+\bb
+\DWTAGskeletonunit
+&\DWATaddrbase{} \\*
+&\DWATcompdir{} \\*
+&\DWATdwoname{} \\*
+&\DWAThighpc{} \\*
+&\DWATlowpc{} \\*
+&\DWATranges{} \\*
+&\DWATrangesbase{} \\*
+&\DWATstmtlist{} \\*
+&\DWATstroffsetsbase{} \\*
+&\DWATuseUTFeight{}
+\eb
+\\
+
\hline
\DWTAGstringtype
&\livelink{chap:DECL}{DECL} \\*
\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 \\
\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{}
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}
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
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.
\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}
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
\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.}
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}
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
\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 \\
\DWTAGatomictype~\ddag & 0x47 \\
\DWTAGcallsite~\ddag & 0x48 \\
\DWTAGcallsiteparameter~\ddag & 0x49 \\
+\bb
+\DWTAGskeletonunit~\ddag & 0x4a
+\eb
+\\
\DWTAGlouser&0x4080 \\
\DWTAGhiuser&\xffff \\
\end{longtable}
\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} \\
\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} \\
\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 & \\
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
\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
% 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}{}}
% 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
\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
\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
\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}
\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}
\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}
\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
%
\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}}
\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}}
%
\DWTAGrvaluereferencetype,
\DWTAGsettype,
\DWTAGsharedtype,
+\bb
+\DWTAGskeletonunit,
+\eb
\DWTAGstringtype,
\DWTAGstructuretype,
\DWTAGsubprogram,
&\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}
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.}
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
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}
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.
\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.
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.
\end{enumerate}
+\needlines{8}
\subsubsection{Standard Content Descriptions}
\label{chap:standardcontentdescriptions}
DWARF-defined content type codes are used to indicate
\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
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
\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:}
\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.}
\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
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
\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} \\
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
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. ]
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}
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.
(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
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.
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.}
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
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
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."}
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
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
\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}
\DWATaddrbase{},
\DWATcompdir{},
\DWATdwoname{},
-\DWATdwoid{},
+\bbeb %\DWATdwoid{},
\DWAThighpc{},
\DWATlowpc{},
\DWATranges{},
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
\hline
\DWATcompdir & \chkmk & & \chkmk & & \\
\hline
-\DWATdwoid & & & \chkmk & \chkmk & \\
-\hline
+\bbeb %\DWATdwoid & & & \chkmk & \chkmk & \\
+%\hline
\DWATdwoname & & & \chkmk & & \\
\hline
\DWATentrypc & \chkmk & & & \chkmk & \\
\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)
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
\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
\DWATname [\DWFORMstrx]: (slot 12) "Point"
\DWATdeclfile: 1
\DWATdeclline: 5
- \DWATlinkagename [\DWFORMstrx]: (slot 16): "_ZN5PointC4Eff"
+ \DWATlinkagename [\DWFORMstrx]: (slot 16) "_ZN5PointC4Eff"
\DWATaccessibility: \DWACCESSpublic
\DWATdeclaration: true
...
\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
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
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
DWARF Git Projects / dwarf-doc.git / commitdiff