Update Appendix B based on input from Dave Anderson.
[dwarf-doc.git] / dwarf5 / latexdoc / debugsectionrelationships.tex
index 54073f1..9bd9a21 100644 (file)
@@ -4,13 +4,21 @@ DWARF information is organized into multiple program sections,
 each of which holds a particular kind of information. In some 
 cases, information in one section refers to information in one 
 or more of the others. These relationships are illustrated by 
-the diagram and associated notes on the following pages.
+the diagrams and associated notes on the following pages.
 
-\textit{This diagram does not distinguish between the normal
-and split object section pairs (for example, \dotdebuginfo{} 
-versus \dotdebuginfodwo). Similarly, it does not show the 
-relationship between the main debugging sections of an executable
-or sharable file and a related \addtoindex{supplementary object file}.}
+\section{Normal DWARF Section Relationships}
+Figure \referfol{fig:debugsectionrelationships} illustrates
+the DWARF section relations without split DWARF object files
+involved. Similarly, it does not show the 
+relationships between the main debugging sections of an executable
+or sharable file and a related \addtoindex{supplementary object file}.
+
+\section{Split DWARF Section Relationships}
+Figure \ref{fig:splitdwarfsectionrelationships} illustrates
+the DWARF section relationships for split DWARF object files.
+However, it does not show the 
+relationships between the main debugging sections of an executable
+or sharable file and a related \addtoindex{supplementary object file}.
 
 \begin{landscape}
 \begin{figure}
@@ -18,9 +26,10 @@ or sharable file and a related \addtoindex{supplementary object file}.}
 \begin{tikzpicture}
     [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15, 
         inner sep=.2cm, minimum width=4.0cm},
-        link/.style={rectangle,                       draw,
-        inner sep=.2cm, minimum width=4.5cm}]
-
+     link/.style={rectangle,                       draw,
+        inner sep=.2cm, minimum width=4.5cm},
+     circ/.style={circle,                          draw, minimum size=0.5cm}]
+     
 % The first (leftmost) column, first sections, then links, from top to bottom
 %
 \node(zsectara) at ( 0, 15.0) [sect] {\dotdebugaranges};
@@ -28,17 +37,19 @@ or sharable file and a related \addtoindex{supplementary object file}.}
 \node(zsectinf) at ( 0,  7.5) [sect] {\begin{tabular}{c} 
                                      \dotdebuginfo 
                                      \end{tabular}};
+\node(zcircs)   at (-1,  5  ) [circ] {(s)};
 \node(zlinkb)   at ( 0,  1.5) [link] {To compilation unit~~(b)};
 \node(zsectpub) at ( 0,  0.0) [sect] {\begin{tabular}{c} 
                                      \dotdebugnames  
                                      \end{tabular}};
-
+                                      
+\draw[thick,angle 90-]                  (zcircs) -- (zsectinf);
 \draw[thick,-to reversed]              (zlinka) -- (zsectara);
 \draw[thick,angle 90-]                         (zsectinf) -- (zlinka);
 \draw[thick,-angle 90]                         (zlinkb) -- (zsectinf);
 \draw[thick,to reversed-]              (zsectpub) -- (zlinkb);
 
-% The seond column, similarly
+% The second column, similarly
 %
 \node(zsectfra) at (5, 15.0)  [sect] {\dotdebugframe};
 \node(zlinkc)   at (5, 13.5)  [link] {To abbreviations~~(c)};
@@ -129,18 +140,21 @@ or sharable file and a related \addtoindex{supplementary object file}.}
                                         \DWMACROundefindirect \\
                                         (p)
                                         \end{tabular}};
-\node(zlinkz)   at (15.6,  6.0) [link] {\begin{tabular}{c}
+\node(zlinkz)   at (15.6,  6.4) [link] {\begin{tabular}{c}
                                         \DWMACROtransparentinclude \\
                                         (q)
                                         \end{tabular}};
 \node(zlinkx)   at (15.6,  3.8) [link]  {\DWFORMlinestrp~(r)};
 \node(zsectlns) at (15.6,  2.0) [sect]  {\dotdebuglinestr};
-                                        
+\node(zcircsp)  at (15.6,  0.5) [circ]  {(s)'};             
+             
 \draw[thick,to reversed-]       (zsectmac.east) -- (zlinky);
 \draw[thick,-angle 90]          (zlinky) -- (zsectstr.east);
 \draw[<->,thick]               (zsectmac.east) -- (zlinkz);
 \draw[thick,to reversed-]       (zsectlin.east) -- (zlinkx);
-\draw[thick, -angle 90]         (zlinkx) -- (zsectlns);
+\draw[thick,-angle 90]          (zlinkx) -- (zsectlns);
+\draw[thick,-angle 90]          (zcircsp) -- (zsectlns);
+
 \end{tikzpicture}
 \vspace{5mm}
 \caption{Debug section relationships}
@@ -150,10 +164,10 @@ or sharable file and a related \addtoindex{supplementary object file}.}
 
 \clearpage
 \begin{center}
-   \textbf{Notes}
+   \textbf{Notes for Figure \ref{fig:debugsectionrelationships}}
 \end{center}
-\begin{enumerate}[(a)]  
-\item  \dotdebugaranges{} to \dotdebuginfo \\
+\begin{description} 
+\itembfnl{(a) \dotdebugaranges{} to \dotdebuginfo}
 The \texttt{debug\_info\_offset} value in
 the header is
 the offset in the \dotdebuginfo{} section of the
@@ -161,27 +175,27 @@ corresponding compilation unit header (not the compilation
 unit entry).
 
 %b
-\item \dotdebugnames{} to \dotdebuginfo \\
+\itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
 The \texttt{debug\_info\_offset} value in the header is the offset in the
 \dotdebuginfo{} section of the 
 corresponding compilation unit header (not
 the compilation unit entry). 
 
 %c
-\item \dotdebuginfo{} to \dotdebugabbrev \\
+\itembfnl{(c) \dotdebuginfo{} to \dotdebugabbrev}
 The \texttt{debug\_abbrev\_offset} value in the header is the offset in the
 \dotdebugabbrev{} 
 section of the abbreviations for that compilation unit.
 
 %d
-\item  \dotdebuginfo{} to \dotdebugstr \\
+\itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
 Attribute values of class string may have form 
 \DWFORMstrp, whose
 value is the offset in the \dotdebugstr{}
 section of the corresponding string.
 
 %e
-\item \dotdebuginfo{} to \dotdebugstroffsets \\
+\itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
 The value of the \DWATstroffsetsbase{} attribute in a
 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{} 
 DIE is the offset in the
@@ -193,7 +207,7 @@ In addition, attribute values of class string may have form
 string offsets table.
 
 %f
-\item \dotdebuginfo{} to \dotdebuginfo \\
+\itembfnl{(f) \dotdebuginfo{} to \dotdebuginfo}
 The operand of the \DWOPcallref{} 
 DWARF expression operator is the
 offset of a debugging information entry in the 
@@ -202,7 +216,7 @@ Similarly for attribute operands that use
 \DWFORMrefaddr.
 
 %g
-\item \dotdebuginfo{} to \dotdebugmacro \\
+\itembfnl{(g) \dotdebuginfo{} to \dotdebugmacro}
 An attribute value of class 
 \livelink{chap:classmacptr}{macptr} (specifically form
 \DWFORMsecoffset) is an 
@@ -211,7 +225,7 @@ offset within the
 of the beginning of the macro information for the referencing unit.
 
 %h
-\item \dotdebuginfo{} to \dotdebugline \\
+\itembfnl{(h) \dotdebuginfo{} to \dotdebugline}
 An attribute value of class 
 \livelink{chap:classlineptr}{lineptr} (specifically form
 \DWFORMsecoffset) 
@@ -221,7 +235,7 @@ beginning of the line number information for the referencing unit.
 
 %i
 \needlines{5}
-\item \dotdebuginfo{} to \dotdebugranges \\
+\itembfnl{(i) \dotdebuginfo{} to \dotdebugranges}
 An attribute value of class \livelink{chap:classrangelistptr}{rangelistptr} 
 (specifically form
 \DWFORMsecoffset) 
@@ -229,7 +243,7 @@ is an offset within the \dotdebugranges{} section of
 a range list.
 
 %j
-\item \dotdebuginfo{} to \dotdebugloc \\
+\itembfnl{(j) \dotdebuginfo{} to \dotdebugloc}
 An attribute value of class \livelink{chap:classloclistptr}{loclistptr} 
 (specifically form
 \DWFORMsecoffset) 
@@ -238,7 +252,7 @@ section of a
 \addtoindex{location list}.
 
 %k
-\item \dotdebuginfo{} to \dotdebugaddr \\
+\itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
 The value of the \DWATaddrbase{} attribute in the
 \DWTAGcompileunit{} or \DWTAGpartialunit{} DIE is the
 offset in the \dotdebugaddr{} section of the machine
@@ -247,13 +261,13 @@ addresses for that unit.
 indices relative to that offset.
 
 %l
-\item \dotdebugstroffsets{} to \dotdebugstr \\
+\itembfnl{(l) \dotdebugstroffsets{} to \dotdebugstr}
 Entries in the string offsets table
 are offsets to the corresponding string text in the 
 \dotdebugstr{} section.
 
 %m
-\item \dotdebugmacro{} to \dotdebugstroffsets \\
+\itembfnl{(m) \dotdebugmacro{} to \dotdebugstroffsets}
 The second operand of a 
 \DWMACROdefineindirectx{} or \DWMACROundefindirectx{} 
 macro information entry is an index
@@ -261,22 +275,22 @@ into the string offset table in the
 \dotdebugstroffsets{} section.
 
 %n
-\item \dotdebugmacro{} to \dotdebugline \\
+\itembfnl{(n) \dotdebugmacro{} to \dotdebugline}
 The second operand of 
 \DWMACROstartfile{} refers to a file entry in the 
 \dotdebugline{} section relative to the start 
 of that section given in the macro information header.
 
 %o
-\item \dotdebugloc{} to \dotdebugaddr \\
+\itembfnl{(o) \dotdebugloc{} to \dotdebugaddr}
 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the 
 \dotdebugloc{} section refer indirectly to the 
 \dotdebugaddr{} section by way of the 
 \DWATaddrbase{} attribute in the associated \dotdebuginfo{} 
-section. F
+section.
 
 %p
-\item \dotdebugmacro{} to \dotdebugstr \\
+\itembfnl{(p) \dotdebugmacro{} to \dotdebugstr}
 The second operand of a 
 \DWMACROdefineindirect{} or \DWMACROundefindirect{} macro information
 entry is an index into the string table in the 
@@ -284,7 +298,7 @@ entry is an index into the string table in the
 
 %q
 \needlines{4}
-\item \dotdebugmacro{} to \dotdebugmacro \\
+\itembfnl{(q) \dotdebugmacro{} to \dotdebugmacro}
 The operand of a 
 \DWMACROtransparentinclude{} macro information
 entry is an offset into another part of the 
@@ -293,10 +307,225 @@ sequence to be transparently included.
 
 %r
 \needlines{4}
-\item \dotdebugline{} to \dotdebuglinestr \\
+\itembfnl{(r) \dotdebugline{} to \dotdebuglinestr}
 The value of a \DWFORMlinestrp{} form refers to a
 string section specific to the line number table.
 This form can be used in a \dotdebugline{} section
-(as shown) or in a \dotdebuginfo{} section (not shown).
+(as well as in a \dotdebuginfo{} section).
+
+%s
+\itembfnl{(s) \dotdebuginfo{} to \dotdebuglinestr}
+The value of a \DWFORMlinestrp{} form refers to a
+string section specific to the line number table.
+This form can be used in a \dotdebuginfo{} section
+(as well as in a \dotdebugline{} section).\footnote{ 
+The circled (s) connects to the circled
+(s)' via hyperspace (a wormhole).}
+\end{description}
+
+
+
+\begin{landscape}
+\begin{figure}
+%\scriptsize
+\begin{tikzpicture}
+    [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15, 
+        inner sep=.2cm, minimum width=4.0cm},
+     link/.style={rectangle,                       draw,
+        inner sep=.2cm, minimum width=4.5cm}]
+
+\fill[yellow!50] (7.5,-1) -- (7.5,14.5) -- (19,14.5) -- (19,-1) -- cycle;
+
+\node(ysectabb)    at ( 5, 13.5) [sect] {\dotdebugabbrev};
+\node(ysectadd)    at ( 2, 12.0) [sect] {\dotdebugaddr};
+\node(ysectara)    at ( 0, 10.5) [sect] {\dotdebugaranges};
+\node(ysectfra)    at ( 0,  9.0) [sect] {\dotdebugframe};
+\node(ysectlin)    at ( 0,  7.5) [sect] {\dotdebugline};
+\node(ysectlis)    at ( 0,  6.0) [sect] {\dotdebuglinestr};
+\node(ysectnam)    at ( 0,  4.5) [sect] {\dotdebugnames};
+\node(ysectran)    at ( 0,  3.0) [sect] {\dotdebugranges};
+\node(ysectstr)    at ( 2,  1.5) [sect] {\dotdebugstr};
+\node(ysectsto)    at ( 5,  0.0) [sect] {\dotdebugstroffsets};
+
+\node(ysectinf)    at ( 5,  7) [sect] {\begin{tabular}{c}
+                                         \dotdebuginfo \\
+                                         skeleton
+                                         \end{tabular}};
+
+\node(ysectinfdwo) at (10.5,7) [sect] {\begin{tabular}{c}
+                                         \dotdebuginfodwo \\
+                                         One CU, possibly \\
+                                         multiple COMDAT \\
+                                         type units
+                                         \end{tabular}};
+
+\node(ysectabbdwo) at (10.5, 13.5) [sect] {\dotdebugabbrevdwo};
+\node(ysectlindwo) at (16.0,  7.5) [sect] {\dotdebuglinedwo};
+\node(ysectlocdwo) at (16.0, 11.0) [sect] {\dotdebuglocdwo};
+\node(ysectmacdwo) at (16.0,  4.5) [sect] {\dotdebugmacrodwo};
+\node(ysectstrdwo) at (13.0,  2.0) [sect] {\dotdebugstrdwo};
+\node(ysectstodwo) at (10.5,  0.0) [sect] {\dotdebugstroffsetsdwo};
+
+\draw[thick,-angle 90] (ysectinf) -- (ysectabb) node[midway, right] {(c)};
+\draw[thick,-angle 90] (ysectinf) -- (ysectadd) node[midway, right] {(k)};
+\draw[thick,-angle 90] (ysectara.east) -- (ysectinf) node[midway, left] {(a)};
+\draw[thick,-angle 90] (ysectinf) -- (ysectlin) node[midway, above] {(h)};
+\draw[thick,-angle 90] (ysectlin) -- (ysectlis) node[midway, right] {(l)};
+\draw[thick,-angle 90] (ysectnam.east) -- (ysectinf) node[midway, left] {(b)};
+\draw[thick,-angle 90] (ysectinf) -- (ysectran.east) node[left, near end] {(i)};
+\draw[thick,-angle 90] (ysectinf) -- (ysectstr) node[midway, right] {(d)};
+\draw[thick,-angle 90] (ysectinf) -- (ysectsto) node[midway, right] {(e)};
+\draw[thick,-angle 90] (ysectsto) -- (ysectstr) node[midway, right] {(l)};
+
+\draw[dashed, thick,-angle 90]  (ysectinf) .. controls (7.5, 12) ..(ysectinfdwo) 
+                                                       node[midway, above] {(did)};
+
+\draw[thick,-angle 90]  (ysectinfdwo) -- (ysectabbdwo) node[midway, right] {(co)};
+\draw[thick,-angle 90]  (ysectinfdwo) -- (ysectlindwo) node[midway, above] {(ho)};
+\draw[thick,-angle 90]  (ysectinfdwo) -- (ysectlocdwo.west) node[midway, below] {(jo)};
+\draw[thick,-angle 90]  (ysectinfdwo) -- (ysectmacdwo.west) node[near end, above] {(go)};
+\draw[thick,-angle 90]  (ysectinfdwo) -- (ysectstrdwo) node[midway, right] {(do)};
+\draw[thick,-angle 90]  (ysectinfdwo) -- (ysectstodwo) node[midway, left] {(eo)};
+
+\draw[thick,-angle 90]  (ysectstodwo) -- (ysectstrdwo) node[near end, below] {(lo)};
+\draw[thick,-angle 90]  (ysectmacdwo) -- (ysectstrdwo) node[midway, left] {(po)};
+\draw[thick,-angle 90]  (ysectmacdwo) .. controls (16.5, 1) .. (ysectstodwo.east)
+                                                       node[near start, left] {(mo)};
+\draw[thick,-angle 90]  (ysectlindwo.east) .. controls (19,4) and (18, 0) .. (ysectstodwo.east)
+                                                       node[very near start, left] {(lmo)};
+
+\draw (0,  14) node {\begin{tabular}{l} Skeleton DWARF \\ in executable \end{tabular}};
+\draw (17, 14) node {\begin{tabular}{r} Split DWARF \\ in separate object \end{tabular}};                                                
+\end{tikzpicture}
+\vspace{3mm}
+\caption{Split DWARF section relationships}
+\label{fig:splitdwarfsectionrelationships}
+\end{figure}
+\end{landscape}
+
+\clearpage
+\begin{center}
+   \textbf{Notes for Figure \ref{fig:splitdwarfsectionrelationships}}
+\end{center}
+\begin{description}
+\itembfnl{(a)  \dotdebugaranges{} to \dotdebuginfo}
+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.
+
+\itembfnl{(b) \dotdebugnames{} to \dotdebuginfo}
+The \dotdebugnames{} section  offsets lists provide an offset
+for the skeleton compilation unit and eight 
+byte signatures for the type units that appear only in the 
+\dotdebuginfodwo. The DIE offsets for these 
+compilation units and type units refer to the DIEs in the 
+\dotdebuginfodwo{} section for the respective 
+compilation unit and type units.
+
+\itembfnl{(c) \dotdebuginfo{} skeleton to \dotdebugabbrev}
+The \texttt{debug\_abbrev\_offset} value in the header is 
+the offset in the \dotdebugabbrev{} section of the 
+abbreviations for that compilation unit skeleton.
+
+\itembfnl{(co) \dotdebuginfodwo{} to \dotdebugabbrevdwo}
+The \texttt{debug\_abbrev\_offset} value in the header 
+is the offset in the \dotdebugabbrevdwo{} section of the 
+abbreviations for that compilation unit.
+
+\itembfnl{(d) \dotdebuginfo{} to \dotdebugstr}
+Attribute values of class string may have form \DWFORMstrp, 
+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. 
+
+\itembfnl{(do) \dotdebuginfodwo{} to \dotdebugstrdwo}
+Attribute values of class string may have form 
+\DWFORMstrp, whose value is an offset in the 
+\dotdebugstrdwo{} section of the corresponding string.
+
+\itembfnl{(e) \dotdebuginfo{} to \dotdebugstroffsets}
+Attribute values of class string may have form 
+\DWFORMstrx, whose value is an index into  the 
+\dotdebugstroffsets{} section for the corresponding string.
+
+\needlines{4}
+\itembfnl{(eo)\dotdebuginfodwo{} to \dotdebugstroffsetsdwo}
+Attribute values of class string may have form 
+\DWFORMstrx, whose value is an index into  the 
+\dotdebugstroffsetsdwo{} section for the corresponding string.
+
+\itembfnl{(fo) \dotdebuginfodwo{} to \dotdebuginfodwo}
+The operand of the \DWOPcallref{} DWARF expression 
+operator is the offset of a debugging 
+information entry in the \dotdebuginfodwo{} section of 
+another compilation unit.  Similarly for attribute 
+operands that use \DWFORMrefaddr. 
+See Section \refersec{chap:controlflowoperations}.
+
+\itembfnl{(go) \dotdebuginfodwo{} to \dotdebugmacrodwo}
+An attribute of class \CLASSmacptr{} (specifically \DWATmacros{} 
+with form \DWFORMsecoffset{}) is an offset within the 
+\dotdebugmacrodwo{} section of the beginning of the macro 
+information for the referencing unit.
+
+\itembfnl{(h) \dotdebuginfo{} (skeleton) to \dotdebugline}
+An attribute value of class \CLASSlineptr{} (specifically 
+\DWATstmtlist{} with form \DWFORMsecoffset) 
+is an offset within the \dotdebugline{} section of the 
+beginning of the line number information for the 
+referencing unit.
+
+\itembfnl{(ho) \dotdebuginfodwo{}  to \dotdebuglinedwo{} (skeleton)}
+An attribute value of class \CLASSlineptr{} (specifically  
+\DWATstmtlist{}  with form \DWFORMsecoffset) 
+is an offset within the \dotdebuglinedwo{} section of the 
+beginning of the line number header information 
+for the referencing unit (the line table details are not in 
+\dotdebuglinedwo{} but the line header with its list 
+of file names is present).
+
+\itembfnl{(i) \dotdebuginfo{} to \dotdebugranges}
+An attribute value of class \CLASSrangelistptr{} 
+(specifically \DWATranges{} with form 
+\DWFORMsecoffset) is an offset within the \dotdebugranges{} 
+section of a range list.
+
+\itembfnl{(jo) \dotdebuginfodwo{} to \dotdebuglocdwo}
+An attribute value of class \CLASSloclistptr{} (specifically 
+\DWATdatamemberlocation,
+\DWATframebase,
+\DWATlocation, 
+\DWATreturnaddr, 
+\DWATsegment, 
+\DWATstaticlink,
+\DWATstringlength, 
+\DWATuselocation{} or 
+\DWATvtableelemlocation{}
+with form \DWFORMsecoffset) is an offset within the 
+\dotdebuglocdwo{} section of a location list.  The format of
+\dotdebuglocdwo{} location list entries is slightly different 
+than that in \dotdebugloc. 
+See Section \refersec{chap:locationlistsinsplitobjects} for details.
+
+\needlines{4}
+\itembfnl{(k) \dotdebuginfo{} to \dotdebugaddr}
+The value of the \DWATaddrbase{} attribute in the 
+\DWTAGcompileunit, \DWTAGpartialunit{} or \DWTAGtypeunit{} DIE 
+is the offset in the \dotdebugaddr{} section of the machine 
+addresses for that unit.
+\DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain indices 
+relative to that offset.
 
-\end{enumerate}
+\end{description}
\ No newline at end of file