be74798e0e47a1169003256c3a2b8cf6edf34cde
[dwarf-doc.git] / dwarf5 / latexdoc / debugsectionrelationships.tex
1 \chapter{Debug Section Relationships (Informative)}
2 \label{app:debugsectionrelationshipsinformative}
3 %
4 DWARF information is organized into multiple program sections, 
5 each of which holds a particular kind of information. In some 
6 cases, information in one section refers to information in one 
7 or more of the others. These relationships are illustrated by 
8 the diagram and associated notes on the following pages.
9
10 \begin{figure}[h]
11 \small
12 \begin{tikzpicture}
13     [sect/.style={rectangle, rounded corners, draw, fill=blue!20, inner sep=.2cm, minimum width=4.5cm},
14          link/.style={rectangle,                  draw,               inner sep=.2cm, minimum width=5.0cm}]
15
16 % The left column, first sections, then links, from top to bottom
17 %
18 \node(zsectara) at ( 0, 10.) [sect] {\dotdebugaranges};
19 \node(zlinka)   at ( 0, 8.0) [link] {To compilation unit (a)};
20 \node(zsectinf) at ( 0, 5.0) [sect] {\begin{tabular}{c} \dotdebuginfo \\ \dotdebugtypes \end{tabular}};
21 \node(zlinkb)   at ( 0, 2.0) [link] {To compilation unit (b)};
22 \node(zsectpub) at ( 0, 0.0) [sect] {\begin{tabular}{c} \dotdebugpubnames \\ \dotdebugpubtypes \end{tabular}};
23
24 \draw[thick,-o]        (zlinka) -- (zsectara);
25 \draw[thick,angle 90-] (zsectinf) -- (zlinka);
26 \draw[thick,-angle 90] (zlinkb) -- (zsectinf);
27 \draw[thick,o-]        (zsectpub) -- (zlinkb);
28
29 % The middle column, similarly
30 %
31 \node(zsectfra) at (6, 10.) [sect] {\dotdebugframe};
32 \node(zlinkc)   at (6,  8.) [link] {To abbreviations (c)};
33 \node(zlinkd)   at (6,  7.) [link] {\DWFORMstrp{} (d)};
34 \node(zlinke)   at (6,  6.) [link] {\DWOPcallref{} (e)};
35 \node(zlinkf)   at (6,  5.) [link] {\DWATlocation{}, etc. (f)};
36 \node(zlinkg)   at (6,  4.) [link] {\DWATranges{} (g)};
37 \node(zlinkh)   at (6,  3.) [link] {\DWATmacroinfo{} (h)};
38 \node(zlinki)   at (6,  2.) [link] {\DWATstmtlist{} (i)};
39
40 % Links between left and center
41 %
42 \draw[thick,o-]                 (zsectinf) -- (zlinkc.west);
43 \draw[thick,o-]                 (zsectinf) -- (zlinkd.west);
44 \draw[thick,angle 90-]  (zsectinf) -- (zlinke.west);
45 \draw[thick,o-]                 (zsectinf) -- (zlinkf.west);
46 \draw[thick,o-]                 (zsectinf) -- (zlinkg.west);
47 \draw[thick,o-]                 (zsectinf) -- (zlinkh.west);
48 \draw[thick,o-]                 (zsectinf) -- (zlinki.west);
49
50 % The right column
51 %
52 \node(zsectabb) at (12, 10) [sect] {\dotdebugabbrev};
53 \node(zsectstr) at (12,  8) [sect] {\dotdebugstr};
54 \node(zsectloc) at (12,  6) [sect] {\dotdebugloc};
55 \node(zsectran) at (12,  4) [sect] {\dotdebugranges};
56 \node(zsectmac) at (12,  2) [sect] {\dotdebugmacinfo};
57 \node(zsectlin) at (12,  0) [sect] {\dotdebugline};
58
59 % Links between center and right
60 %
61 \draw[thick,-angle 90]          (zlinkc.east) -- (zsectabb.west);
62 \draw[thick,-angle 90]          (zlinkd.east) -- (zsectstr.west);
63 \draw[thick,-o]                         (zlinke.east) -- (zsectloc.west);
64 \draw[thick,-angle 90]          (zlinkf.east) -- (zsectloc.south west);
65 \draw[thick,-angle 90]          (zlinkg.east) -- (zsectran.west);
66 \draw[thick,-angle 90]          (zlinkh.east) -- (zsectmac.west);
67 \draw[thick,-angle 90]          (zlinki.east) -- (zsectlin.west);
68
69 \end{tikzpicture}
70
71 \vspace{1cm}
72 \caption{Debug section relationships}
73 \label{fig:debugsectionrelationships}
74 \end{figure}
75
76 \clearpage
77 \begin{center}
78    \textbf{Notes}
79 \end{center}
80 \begin{enumerate}[(a)]  
81 \item  \addtoindex{.debug\_aranges}  \\
82 The debug\_info\_offset value in
83 the header is
84 the offset in the \addtoindex{.debug\_info} section of the
85 corresponding compilation unit header (not the compilation
86 unit entry).
87
88 %b
89 \item \addtoindex{.debug\_pubnames} and \addtoindex{.debug\_pubtypes} \\
90 The debug\_info\_offset value in the header is the offset in the
91 \addtoindex{.debug\_info} section of the 
92 corresponding compilation unit header (not
93 the compilation unit entry). Each pubname/pubtype has the offset (within
94 the corresponding compilation unit) of the applicable debugging
95 information entry.
96
97 %c
98 \item \addtoindex{.debug\_info} and \addtoindex{.debug\_types} \\
99 The debug\_abbrev\_offset value in the header is the offset in the
100 \addtoindex{.debug\_abbrev} 
101 section of the abbreviations for that compilation unit.
102
103 %d
104 \item  \addtoindex{.debug\_info} and \addtoindex{.debug\_types} \\
105 Attribute values of class string may have form 
106 \livelink{chap:DWFORMstrp}{DW\-\_FORM\-\_strp}, whose
107 value is the offset in the \addtoindex{.debug\_str}
108 section of the corresponding string.
109
110 %e
111 \item \addtoindex{.debug\_loc} \\
112 The operand of the \livelink{chap:DWOPcallref}{DW\-\_OP\-\_call\-\_ref} 
113 DWARF expression operator is the
114 offset of a debugging information entry in the 
115 \addtoindex{.debug\_info} section.
116
117 %f
118 \item \addtoindex{.debug\_info} \\
119 An attribute value of class \livelink{chap:loclistptr}{loclistptr} 
120 (specifically form
121 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) 
122 is an offset within the \addtoindex{.debug\_loc} 
123 section of a
124 \addtoindex{location list}.
125
126 %g
127 \item \addtoindex{.debug\_info} \\
128 An attribute value of class \livelink{chap:rangelistptr}{rangelistptr} 
129 (specifically form
130 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) 
131 is an offset within the \addtoindex{.debug\_ranges} section of
132 a range list.
133
134 %h
135 \item \addtoindex{.debug\_info} \\
136 An attribute value of class 
137 \livelink{chap:macptr}{macptr} (specifically form
138 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) is an 
139 offset within the 
140 \addtoindex{.debug\_macinfo} section
141 of the beginning of the macro information for the referencing unit.
142
143 %i
144 \item \addtoindex{.debug\_info} \\
145 An attribute value of class 
146 \livelink{chap:lineptr}{lineptr} (specifically form
147 \livelink{chap:DWFORMsecoffset}{DW\-\_FORM\-\_sec\-\_offset}) 
148 is an offset in the 
149 \addtoindex{.debug\_line} section of the
150 beginning of the line number information for the referencing unit.
151 \end{enumerate}