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