f6c7ac5440b41894ec594fda0a314a93f2a991b7
[dwarf-doc.git] / dwarf5 / latexdoc / debugsectionrelationships.tex
1 \chapter{Debug Section Relationships (Informative)}
2 \label{app:debugsectionrelationshipsinformative}
3 DWARF information is organized into multiple program sections, 
4 each of which holds a particular kind of information. In some 
5 cases, information in one section refers to information in one 
6 or more of the others. These relationships are illustrated by 
7 the diagram and associated notes on the following pages.
8
9 \textit{This diagram does not distinguish between the normal
10 and split object section pairs (for example, \dotdebuginfo{} 
11 versus \dotdebuginfodwo).}
12
13 \clearpage
14 \begin{landscape}
15 \begin{figure}[H]
16 \scriptsize
17 \begin{tikzpicture}
18     [sect/.style={rectangle, rounded corners=10pt, draw, fill=blue!15, 
19         inner sep=.2cm, minimum width=4.0cm},
20          link/.style={rectangle,                       draw,
21         inner sep=.2cm, minimum width=4.5cm}]
22
23 % The left column, first sections, then links, from top to bottom
24 %
25 \node(zsectara) at ( 0, 15.0) [sect] {\dotdebugaranges};
26 \node(zlinka)   at ( 0, 13.5) [link] {To compilation unit~~(a)};
27 \node(zsectinf) at ( 0,  7.5) [sect] {\begin{tabular}{c} 
28                                                                          \dotdebuginfo 
29                                                                          \end{tabular}};
30 \node(zlinkb)   at ( 0,  1.5) [link] {To compilation unit~~(b)};
31 \node(zsectpub) at ( 0,  0.0) [sect] {\begin{tabular}{c} 
32                                                                          \dotdebugpubnames \\ 
33                                                                          \dotdebugpubtypes 
34                                                                          \end{tabular}};
35
36 \draw[thick,-to reversed]               (zlinka) -- (zsectara);
37 \draw[thick,angle 90-]                  (zsectinf) -- (zlinka);
38 \draw[thick,-angle 90]                  (zlinkb) -- (zsectinf);
39 \draw[thick,to reversed-]               (zsectpub) -- (zlinkb);
40
41 % The middle column, similarly
42 %
43 \node(zsectfra) at (5, 15.0)  [sect] {\dotdebugframe};
44 \node(zlinkc)   at (5, 13.5)  [link] {To abbreviations~~(c)};
45 \node(zlinkd)   at (5, 12.1)  [link] {\DWFORMstrp{}~~(d)};
46 \node(zlinke)   at (5, 10.4)  [link] {\begin{tabular}{c}
47                                                                           \DWATstroffsetsbase \\
48                                                                           \DWFORMstrx{}~~~~~~~~~(e) \\
49                                                                           \end{tabular}};
50 \node(zlinkf)   at (5,  8.4)  [link] {\begin{tabular}{c}
51                                                                           \DWOPcallref{}~~~~~(f) \\
52                                                                           \DWFORMrefaddr
53                                                                           \end{tabular}};
54 \node(zlinki)   at (5,  6.7)  [link] {\DWATmacros{}~~(g)};
55 \node(zlinkj)   at (5,  5.4)  [link] {\DWATstmtlist{}~~(h)};
56 \node(zlinkh)   at (5,  3.9)  [link] {\begin{tabular}{c}
57                                       \DWATranges{}~~~~(i) \\
58                                       \DWATrangesbase
59                                       \end{tabular}};
60 \node(zlinkg)   at (5,  2.4)  [link] {\DWATlocation{}, etc.~~(j)};
61 \node(zlinkk)   at (5,  0.5)  [link] {\begin{tabular}(c)
62                                                                           \DWATaddrbase    \\
63                                                                           \DWFORMaddrx \\
64                                                                           \DWOPaddrx \\
65                                                                           \DWOPconstx
66                                                                           \end{tabular} (k)};
67
68 % Links between left and center
69 %
70 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkc.west);
71 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkd.west);
72 \draw[thick,to reversed-]                       (zsectinf) -- (zlinke.west);
73 \draw[<->,thick]                                        (zsectinf) -- (zlinkf.west);
74 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkg.west);
75 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkh.west);
76 \draw[thick,to reversed-]                       (zsectinf) -- (zlinki.west);
77 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkj.west);
78 \draw[thick,to reversed-]                       (zsectinf) -- (zlinkk.north west);
79
80 % The right column
81 %
82 \node(zsectabb) at (10, 15.00) [sect] {\dotdebugabbrev};
83 \node(zsectstr) at (10, 13.75) [sect] {\dotdebugstr};
84 \node(zlinkl)   at (10, 12.50) [link] {To strings~~(l)};
85 \node(zsectstx) at (10, 11.25) [sect] {\dotdebugstroffsets};
86 \node(zlinkm)   at (10,  9.50) [link] {\begin{tabular}{c}
87                                       \DWMACROdefineindirectx \\
88                                       \DWMACROundefindirectx \\
89                                       (m)
90                                       \end{tabular}};
91 \node(zsectmac) at (10,  7.80) [sect] {\dotdebugmacro};
92 \node(zlinkn)   at (10,  6.40) [link] {\begin{tabular}{c}
93                                       macroinfo header~~~~~~(n)\\
94                                       \DWMACROstartfile
95                                       \end{tabular}};
96 \node(zsectlin) at (10,  5.00) [sect] {\dotdebugline};
97 \node(zsectran) at (10,  3.85) [sect] {\dotdebugranges};
98 \node(zsectloc) at (10,  2.70) [sect] {\dotdebugloc{}};
99 \node(zlinko)   at (10,  1.20) [link] {\begin{tabular}{c}
100                                        \DWOPaddrx \\
101                                        \DWOPconstx
102                                        \end{tabular} (o)};
103 \node(zsectadx) at (10,  -0.25) [sect] {\dotdebugaddr{}};
104
105 \draw[thick,to reversed-]               (zsectstx) -- (zlinkl);
106 \draw[thick,-angle 90]                  (zlinkl) -- (zsectstr);
107 \draw[thick,to reversed-]       (zsectmac) -- (zlinkm);
108 \draw[thick,-angle 90]          (zlinkm) -- (zsectstx);
109 \draw[thick,to reversed-]       (zsectmac) -- (zlinkn);
110 \draw[thick,-angle 90]          (zlinkn) -- (zsectlin);
111 \draw[thick,to reversed-]       (zsectloc) -- (zlinko);
112 \draw[thick,-angle 90]          (zlinko) -- (zsectadx);
113
114 % Links between center and right
115 %
116 \draw[thick,-angle 90]          (zlinkc.east) -- (zsectabb.west);
117 \draw[thick,-angle 90]          (zlinkd.east) -- (zsectstr.west);
118 \draw[thick,-angle 90]          (zlinke.east) -- (zsectstx.west);
119 \draw[thick,-angle 90]          (zlinkg.east) -- (zsectloc.west);
120 \draw[thick,-angle 90]          (zlinkh.east) -- (zsectran.west);
121 \draw[thick,-angle 90]          (zlinki.east) -- (zsectmac.west);
122 \draw[thick,-angle 90]          (zlinkj.east) -- (zsectlin.west);
123 \draw[thick,-angle 90]          (zlinkk.east) -- (zsectadx.west);
124
125 \node(zlinky)   at (15.5, 10.5) [link] {\begin{tabular}{c}
126                                         \DWMACROdefineindirect \\
127                                         \DWMACROundefindirect \\
128                                         (p)
129                                         \end{tabular}};
130 \node(zlinkz)   at (15.5,  6.0) [link] {\begin{tabular}{c}
131                                         \DWMACROtransparentinclude \\
132                                         (q)
133                                         \end{tabular}};
134
135 \draw[thick,to reversed-]       (zsectmac.east) -- (zlinky);
136 \draw[thick,-angle 90]          (zlinky) -- (zsectstr.east);
137 \draw[<->,thick]                                (zsectmac.east) -- (zlinkz);
138
139 \end{tikzpicture}
140 \vspace{5mm}
141 \caption{Debug section relationships}
142 \label{fig:debugsectionrelationships}
143 \end{figure}
144 \end{landscape}
145
146 \clearpage
147 \begin{center}
148    \textbf{Notes}
149 \end{center}
150 \begin{enumerate}[(a)]  
151 \item  \dotdebugaranges{} to \dotdebuginfo \\
152 The \texttt{debug\_info\_offset} value in
153 the header is
154 the offset in the \dotdebuginfo{} section of the
155 corresponding compilation unit header (not the compilation
156 unit entry).
157
158 %b
159 \item \dotdebugpubnames{} and \dotdebugpubtypes{} to \dotdebuginfo \\
160 The \texttt{debug\_info\_offset} value in the header is the offset in the
161 \dotdebuginfo{} section of the 
162 corresponding compilation unit header (not
163 the compilation unit entry). Each pubname/pubtype unit has the offset (within
164 the corresponding compilation unit) of the applicable debugging
165 information entry.
166
167 %c
168 \item \dotdebuginfo{} to \dotdebugabbrev \\
169 The \texttt{debug\_abbrev\_offset} value in the header is the offset in the
170 \dotdebugabbrev{} 
171 section of the abbreviations for that compilation unit.
172
173 %d
174 \item  \dotdebuginfo{} to \dotdebugstr \\
175 Attribute values of class string may have form 
176 \DWFORMstrp, whose
177 value is the offset in the \dotdebugstr{}
178 section of the corresponding string.
179
180 %e
181 \item \dotdebugstroffsets{} to \dotdebugstroffsets \\
182 The value of the \DWATstroffsetsbase{} attribute in a
183 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{} 
184 DIE is the offset in the
185 \dotdebugstroffsets{} section of the 
186 \addtoindex{string offsets table}
187 for that unit.
188 In addition, attribute values of class string may have form 
189 \DWFORMstrx, whose value is an index into the
190 string offsets table.
191
192 %f
193 \item \dotdebuginfo{} to \dotdebuginfo \\
194 The operand of the \DWOPcallref{} 
195 DWARF expression operator is the
196 offset of a debugging information entry in the 
197 \dotdebuginfo{} section of another compilation.
198 Similarly for attribute operands that have use
199 \DWFORMrefaddr.
200
201 %g
202 \item \dotdebuginfo{} to \dotdebugmacro \\
203 An attribute value of class 
204 \livelink{chap:classmacptr}{macptr} (specifically form
205 \DWFORMsecoffset) is an 
206 offset within the 
207 \dotdebugmacro{} section
208 of the beginning of the macro information for the referencing unit.
209
210 %h
211 \item \dotdebuginfo{} to \dotdebugline \\
212 An attribute value of class 
213 \livelink{chap:classlineptr}{lineptr} (specifically form
214 \DWFORMsecoffset) 
215 is an offset in the 
216 \dotdebugline{} section of the
217 beginning of the line number information for the referencing unit.
218
219 %i
220 \needlines{5}
221 \item \dotdebuginfo{} to \dotdebugranges \\
222 An attribute value of class \livelink{chap:classrangelistptr}{rangelistptr} 
223 (specifically form
224 \DWFORMsecoffset) 
225 is an offset within the \dotdebugranges{} section of
226 a range list.
227
228 %j
229 \item \dotdebuginfo{} to \dotdebugloc \\
230 An attribute value of class \livelink{chap:classloclistptr}{loclistptr} 
231 (specifically form
232 \DWFORMsecoffset) 
233 is an offset within the \dotdebugloc{} 
234 section of a
235 \addtoindex{location list}.
236
237 %k
238 \item \dotdebuginfo{} to \dotdebugaddr \\
239 The value of the \DWATaddrbase{} attribute in the
240 \DWTAGcompileunit{}, \DWTAGtypeunit{} or \DWTAGpartialunit{} DIE is the
241 offset in the \dotdebugaddr{} section of the machine
242 addresses for that unit.
243 \DWFORMaddrx, \DWOPaddrx{} and \DWOPconstx{} contain
244 indices relative to that offset.
245
246 %l
247 \item \dotdebugstroffsets{} to \dotdebugstr \\
248 Entries in the string offsets table
249 are offsets to the corresponding string text in the 
250 \dotdebugstr{} section.
251
252 %m
253 \item \dotdebugmacro{} to \dotdebugstroffsets \\
254 The second operand of a 
255 \DWMACROdefineindirect{} or \DWMACROundefindirect{} macro information
256 entry is an index into the string table in the 
257 \dotdebugstr{} section.
258
259
260 %n
261 \item \dotdebugmacro{} to \dotdebugline \\
262 The second operand of 
263 \DWMACROstartfile{} refers to a file entry in the 
264 \dotdebugline{} section relative to the start 
265 of that section given in the macro information header.
266
267 %o
268 \item \dotdebugloc{} to \dotdebugaddr \\
269 \DWOPaddrx{} and \DWOPconstx{} operators that occur in the 
270 \dotdebugloc{} section refer indirectly to the 
271 \dotdebugaddr{} section by way of the 
272 \DWATaddrbase{} attribute in the associated \dotdebuginfo{} 
273 section. 
274
275 %p
276 \item \dotdebugmacro{} to \dotdebugstroffsets \\
277 The second operand of a 
278 \DWMACROdefineindirectx{} or \DWMACROundefindirectx{} 
279 macro information entry is an index
280 into the string offset table in the 
281 \dotdebugstroffsets{} section.
282
283 %q
284 \item \dotdebugmacro{} to \dotdebugmacro \\
285 The second operand of a 
286 \DWMACROtransparentinclude{} macro information
287 entry is an offset into another part of the 
288 \dotdebugmacro{} section to the header for the 
289 sequence to be transparently included.
290
291
292 \end{enumerate}