Complete work on live links, cleanup some indexing and redo pagination.
[dwarf-doc.git] / dwarf5 / latexdoc / debugsectionrelationships.tex
index 7ccfccc..e20fd11 100644 (file)
 \chapter{Debug Section Relationships (Informative)}
 \label{app:debugsectionrelationshipsinformative}
+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.
+
+\begin{figure}[H]
+\begin{tikzpicture}
+    [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!10, inner sep=.2cm, minimum width=4.5cm},
+        link/.style={rectangle,                       draw,               inner sep=.2cm, minimum width=5.0cm}]
+
+% The left column, first sections, then links, from top to bottom
 %
-\setlength\maxovaldiam{80pt}
-\thicklines
-\begin{picture}(0,0)
-\footnotesize
-  \put(10,0) { .debug\_aranges }
-  \put(40,0) { \circle{80}}
-  \put(180,0) { .debug\_frame }
-  \put(210,0) { \circle{80}}
-  \put(350,0) { .debug\_abbrev }
-  \put(380,0) { \circle{80}}
-
-  \put(40,-40){\line(0,-1){30}}
-  \put(-10,-90){\framebox(110,20){To compilation unit (a)} }
-  \put(40,-90){\vector(0,-1){35}}
-
-  \put(350,-90) { .debug\_str }
-  \put(380,-90) {\circle{80}}
-
-  \put(10,-180) { .debug\_info }
-  \put(40,-180) {\circle{100}}
-
-
-  \put(350,-180) { .debug\_loc }
-  \put(380,-180) {\circle{80}}
-
-  \put(350,-270) { .debug\_ranges }
-  \put(380,-270) {\circle{80}}
-
-  \put(80,-140){\line(3, 2){90}}
-  \put(170,-90){\framebox(110,20){To abbreviations (c)} }
-  \put(280,-70){\vector( 2, 1){70}}
-
-  \put(90,-150){\line(2, 1){100}}
-  \put(190,-120){\framebox(110,20){\livelink{chap:DWFORMstrp}{DW\-\_FORM\-\_strp} (d)} }
-  \put(300,-100){\vector( 4, 1){35}}
-
-  \put(190,-140){\vector(-2, -1){100}}
-  \put(190,-150){\framebox(110,20){\livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref}(e)} }
-  \put(300,-150){\line(4,-1){40}}
-
-  \put(90,-195){\line(7,2){95}}
-  \put(190,-180){\framebox(110,20){\livelink{chap:DWATlocation}{DW\-\_AT\-\_location}(f)} }
-  \put(300,-180){\vector(1,0){40}}
-
-  \put(90,-195){\line(7,-2){95}}
-  \put(190,-230){\framebox(110,20){\livelink{chap:DWATranges}{DW\-\_AT\-\_ranges} (g)} }
-  \put(300,-230){\vector(4,-3){40}}
-
-  \put(85,-200){\line(3,-2){95}}
-  \put(180,-270){\framebox(110,20){\livelink{chap:DWATmacroinfo}{DW\-\_AT\-\_macro\-\_info} (h)} }
-  \put(230,-270){\vector(3,-2){110}}
-
-  \put(85,-200){\line(1,-1){80}}
-  \put(120,-300){\framebox(110,20){\livelink{chap:DWATstmtlist}{DW\-\_AT\-\_stmt\-\_list} (i)} }
-  \put(180,-300){\vector(1,-2){10}}
-
-  \put(40,-250){\vector(0,1){15}}
-  \put(-10,-270){\framebox(110,20){To compilation unit (b)} }
-  \put(40,-320){\line(0,1){50}}
-
-  \put(0,-360) { .debug\_pubnames }
-  \put(0,-375) { .debug\_pubtypes } 
-  \put(40, -360) { \circle{80}}
-  \put(175,-360) { .debug\_line }
-  \put(210,-360) { \circle{80}}
-  \put(350,-360) { .debug\_macinfo}
-  \put(380,-360) { \circle{80}}
-
-\end{picture}
+\node(zsectara) at ( 0, 10.) [sect] {\dotdebugaranges};
+\node(zlinka)   at ( 0, 8.0) [link] {To compilation unit (a)};
+\node(zsectinf) at ( 0, 5.0) [sect] {\begin{tabular}{c} \dotdebuginfo \\ \dotdebugtypes \end{tabular}};
+\node(zlinkb)   at ( 0, 2.0) [link] {To compilation unit (b)};
+\node(zsectpub) at ( 0, 0.0) [sect] {\begin{tabular}{c} \dotdebugpubnames \\ \dotdebugpubtypes \end{tabular}};
+
+\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 middle column, similarly
+%
+\node(zsectfra) at (6, 10.) [sect] {\dotdebugframe};
+\node(zlinkc)   at (6,  8.) [link] {To abbreviations (c)};
+\node(zlinkd)   at (6,  7.) [link] {\DWFORMstrp{} (d)};
+\node(zlinke)   at (6,  6.) [link] {\DWOPcallref{} (e)};
+\node(zlinkf)   at (6,  5.) [link] {\DWATlocation{}, etc. (f)};
+\node(zlinkg)   at (6,  4.) [link] {\DWATranges{} (g)};
+\node(zlinkh)   at (6,  3.) [link] {\DWATmacroinfo{} (h)};
+\node(zlinki)   at (6,  2.) [link] {\DWATstmtlist{} (i)};
+
+% Links between left and center
+%
+\draw[thick,to reversed-]                      (zsectinf) -- (zlinkc.west);
+\draw[thick,to reversed-]                      (zsectinf) -- (zlinkd.west);
+\draw[thick,angle 90-]                         (zsectinf) -- (zlinke.west);
+\draw[thick,to reversed-]                      (zsectinf) -- (zlinkf.west);
+\draw[thick,to reversed-]                      (zsectinf) -- (zlinkg.west);
+\draw[thick,to reversed-]                      (zsectinf) -- (zlinkh.west);
+\draw[thick,to reversed-]                      (zsectinf) -- (zlinki.west);
+
+% The right column
+%
+\node(zsectabb)        at (12, 10) [sect] {\dotdebugabbrev};
+\node(zsectstr)        at (12,  8) [sect] {\dotdebugstr};
+\node(zsectloc)        at (12,  6) [sect] {\dotdebugloc};
+\node(zsectran)        at (12,  4) [sect] {\dotdebugranges};
+\node(zsectmac)        at (12,  2) [sect] {\dotdebugmacinfo};
+\node(zsectlin)        at (12,  0) [sect] {\dotdebugline};
+
+% Links between center and right
+%
+\draw[thick,-angle 90]         (zlinkc.east) -- (zsectabb.west);
+\draw[thick,-angle 90]         (zlinkd.east) -- (zsectstr.west);
+\draw[thick,-to reversed]      (zlinke.east) -- (zsectloc.west);
+\draw[thick,-angle 90]         (zlinkf.east) -- (zsectloc.south west);
+\draw[thick,-angle 90]         (zlinkg.east) -- (zsectran.west);
+\draw[thick,-angle 90]         (zlinkh.east) -- (zsectmac.west);
+\draw[thick,-angle 90]         (zlinki.east) -- (zsectlin.west);
+
+\end{tikzpicture}
+\vspace{5mm}
+\caption{Debug section relationships}
+\label{fig:debugsectionrelationships}
+\end{figure}
 
 \clearpage
+\begin{center}
+   \textbf{Notes}
+\end{center}
 \begin{enumerate}[(a)]  
-\item  .debug\_aranges  \\
+\item  \dotdebugaranges{}  \\
 The debug\_info\_offset value in
-the header is the offset in the .debug\_info section of the
+the header is
+the offset in the \dotdebuginfo{} section of the
 corresponding compilation unit header (not the compilation
 unit entry).
 
-\item .debug\_pubnames and .debug\_pubtypes \\
+%b
+\item \dotdebugpubnames{} and \dotdebugpubtypes{} \\
 The debug\_info\_offset value in the header is the offset in the
-.debug\_info section of the corresponding compilation unit header (not
+\dotdebuginfo{} section of the 
+corresponding compilation unit header (not
 the compilation unit entry). Each pubname/pubtype has the offset (within
 the corresponding compilation unit) of the applicable debugging
 information entry.
 
-\item .debug\_info and .debug\_types \\
+%c
+\item \dotdebuginfo{} and \dotdebugtypes{} \\
 The debug\_abbrev\_offset value in the header is the offset in the
-.debug\_abbrev section of the abbreviations for that compilation unit.
-(d) .debug\_info and .debug\_types
-Attribute values of class string may have form \livelink{chap:DWFORMstrp}{DW\-\_FORM\-\_strp}, whose
-value is the offset in the .debug\_str section of the corresponding string.
-
-\item  .debug\_info and .debug\_types \\
-Attribute values of class string may have form \livelink{chap:DWFORMstrp}{DW\-\_FORM\-\_strp}, whose
-value is the offset in the .debug\_str section of the corresponding string.
-
-\item .debug\_loc \\
-The operand of the \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} DWARF expression operator is the
-offset of a debugging information entry in the .debug\_info section.
-
-\item .debug\_info \\
-An attribute value of class \livelink{chap:loclistptr}{loclistptr} (specifically form
-\livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) is an offset within the .debug\_loc section of a
-location list.
-
-\item .debug\_info \\
-An attribute value of class \livelink{chap:rangelistptr}{rangelistptr} (specifically form
-\livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) is an offset within the .debug\_ranges section of
+\dotdebugabbrev{} 
+section of the abbreviations for that compilation unit.
+
+%d
+\item  \dotdebuginfo{} and \dotdebugtypes{} \\
+Attribute values of class string may have form 
+\livelink{chap:DWFORMstrp}{DW\_FORM\_strp}, whose
+value is the offset in the \dotdebugstr{}
+section of the corresponding string.
+
+%e
+\item \dotdebugloc{} \\
+The operand of the \livelink{chap:DWOPcallref}{DW\_OP\_call\_ref} 
+DWARF expression operator is the
+offset of a debugging information entry in the 
+\dotdebuginfo{} section.
+
+%f
+\item \dotdebuginfo{} \\
+An attribute value of class \livelink{chap:classloclistptr}{loclistptr} 
+(specifically form
+\livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) 
+is an offset within the \dotdebugloc{} 
+section of a
+\addtoindex{location list}.
+
+%g
+\item \dotdebuginfo{} \\
+An attribute value of class \livelink{chap:classrangelistptr}{rangelistptr} 
+(specifically form
+\livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) 
+is an offset within the \dotdebugranges{} section of
 a range list.
 
-
-\item .debug\_info \\
-An attribute value of class \livelink{chap:macptr}{macptr} (specifically form
-\livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) is an offset within the .debug\_macinfo section
+%h
+\item \dotdebuginfo{} \\
+An attribute value of class 
+\livelink{chap:classmacptr}{macptr} (specifically form
+\livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) is an 
+offset within the 
+\dotdebugmacinfo{} section
 of the beginning of the macro information for the referencing unit.
 
-
-\item .debug\_info \\
-An attribute value of class \livelink{chap:lineptr}{lineptr} (specifically form
-\livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) is an offset in the .debug\_line section of the
+%i
+\item \dotdebuginfo{} \\
+An attribute value of class 
+\livelink{chap:classlineptr}{lineptr} (specifically form
+\livelink{chap:DWFORMsecoffset}{DW\_FORM\_sec\_offset}) 
+is an offset in the 
+\dotdebugline{} section of the
 beginning of the line number information for the referencing unit.
 \end{enumerate}
-
-
-